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