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=u'\\', action_type=u'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).
  • 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

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.

  • 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

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=u'\\', 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)
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).
  • 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.
  • 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.
  • 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)
Parameters: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

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

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

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

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

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=u'\\')

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

CLI Example:

salt 'minion-id' task.clear_trigger <task_name>
salt.modules.win_task.create_folder(name, location=u'\\')

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

True if successful, False if unsuccessful

Return type:

bool

CLI Example:

salt 'minion-id' task.create_folder <folder_name>
salt.modules.win_task.create_task(name, location=u'\\', user_name=u'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:
  • 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:WindowsSystem32tasks).
  • 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, False if unsuccessful

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=u'\\', xml_text=None, xml_path=None, user_name=u'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:WindowsSystem32tasks).
  • 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, False if unsuccessful, A string with the error message if there is an error

Return type:

bool

Raises:

CommandExecutionError

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=u'\\')

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

CLI Example:

salt 'minion-id' task.delete_folder <folder_name>
salt.modules.win_task.delete_task(name, location=u'\\')

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

CLI Example:

salt 'minion-id' task.delete_task <task_name>
salt.modules.win_task.edit_task(name=None, location=u'\\', 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:WindowsSystem32tasks).
  • 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.

Parameters:
  • 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
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.
  • 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 -- 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
Parameters:
  • 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 -- 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
Parameters:
  • force_stop (bool) -- Boolean value that indicates that the task may be terminated by using TerminateProcess.
  • 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:
  • 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

CLI Example:

salt 'minion-id' task.edit_task <task_name> description='This task is awesome'
salt.modules.win_task.info(name, location=u'\\')

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

CLI Example:

salt 'minion-id' task.info <task_name>
salt.modules.win_task.list_actions(name, location=u'\\')

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

CLI Example:

salt 'minion-id' task.list_actions <task_name>
salt.modules.win_task.list_folders(location=u'\\')

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=u'\\')

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=u'\\')

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

CLI Example:

salt 'minion-id' task.list_triggers <task_name>
salt.modules.win_task.run(name, location=u'\\')

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

CLI Example:

salt 'minion-id' task.list_run <task_name>
salt.modules.win_task.run_wait(name, location=u'\\')

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

CLI Example:

salt 'minion-id' task.list_run_wait <task_name>
salt.modules.win_task.status(name, location=u'\\')

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

CLI Example:

salt 'minion-id' task.list_status <task_name>
salt.modules.win_task.stop(name, location=u'\\')

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

CLI Example:

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