From eba45074ce52ced24d0a6efa6f1ae375ac7a3f85 Mon Sep 17 00:00:00 2001 From: twangboy Date: Mon, 15 Apr 2019 10:42:43 -0600 Subject: [PATCH 01/11] Bring 52170 into 2019.2 Mostly documentation fixes --- salt/modules/win_task.py | 1118 ++++++++++++++++++++++---------------- 1 file changed, 640 insertions(+), 478 deletions(-) diff --git a/salt/modules/win_task.py b/salt/modules/win_task.py index 50450e906fee..d28d02909e3a 100644 --- a/salt/modules/win_task.py +++ b/salt/modules/win_task.py @@ -10,16 +10,16 @@ You can list all tasks, folders, triggers, and actions. ''' # Import Python libs -from __future__ import absolute_import, unicode_literals, print_function +from __future__ import absolute_import, print_function, unicode_literals +from datetime import datetime import logging import time -from datetime import datetime # Import Salt libs import salt.utils.platform import salt.utils.winapi -# Import 3rd-party libraries +# Import 3rd Party Libraries try: import pythoncom import win32com.client @@ -321,18 +321,25 @@ def list_tasks(location='\\'): r''' List all tasks located in a specific location in the task scheduler. - :param str location: 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). + Args: + + 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). - :return: Returns a list of tasks. - :rtype: list + Returns: + list: Returns a list of tasks CLI Example: .. code-block:: bash + # 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 ''' # Create the task service object with salt.utils.winapi.Com(): @@ -354,18 +361,25 @@ def list_folders(location='\\'): r''' List all folders located in a specific location in the task scheduler. - :param str location: 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). + Args: + + 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). - :return: Returns a list of folders. - :rtype: list + Returns: + list: Returns a list of folders. CLI Example: .. code-block:: bash + # 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 ''' # Create the task service object with salt.utils.winapi.Com(): @@ -387,20 +401,28 @@ def list_triggers(name, location='\\'): r''' List all triggers that pertain to a task in the specified location. - :param str name: The name of the task for which list triggers. + Args: + + name (str): + The name of the task for which list triggers. - :param str location: 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). + 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). - :return: Returns a list of triggers. - :rtype: list + Returns: + list: Returns a list of triggers. CLI Example: .. code-block:: bash + # List all triggers for a task in the default location salt 'minion-id' task.list_triggers + + # List all triggers for the XblGameSaveTask in the Microsoft\XblGameSave + # location + salt 'minion-id' task.list_triggers XblGameSaveTask Microsoft\XblGameSave ''' # Create the task service object with salt.utils.winapi.Com(): @@ -423,20 +445,29 @@ def list_actions(name, location='\\'): r''' List all actions that pertain to a task in the specified location. - :param str name: The name of the task for which list actions. + Args: - :param str location: 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). + name (str): + The name of the task for which list actions. - :return: Returns a list of actions. - :rtype: list + 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: + list: Returns a list of actions. CLI Example: .. code-block:: bash + # List all actions for a task in the default location salt 'minion-id' task.list_actions + + # List all actions for the XblGameSaveTask in the Microsoft\XblGameSave + # location + salt 'minion-id' task.list_actions XblGameSaveTask Microsoft\XblGameSave ''' # Create the task service object with salt.utils.winapi.Com(): @@ -469,25 +500,30 @@ def create_task(name, - :py:func:`add_action` - :py:func:`add_trigger` - :param str name: The name of the task. This will be displayed in the task - scheduler. + Args: - :param str location: 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). + name (str): + The name of the task. This will be displayed in the task scheduler. - :param str user_name: The user account under which to run the task. To - specify the 'System' account, use 'System'. The password will be - ignored. + 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). - :param str password: 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. + user_name (str): + The user account under which to run the task. To specify the + 'System' account, use 'System'. The password will be ignored. - :param bool force: If the task exists, overwrite the existing task. + 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. - :return: True if successful, False if unsuccessful - :rtype: bool + force (bool): + If the task exists, overwrite the existing task. + + Returns: + bool: ``True`` if successful, otherwise ``False`` CLI Example: @@ -547,29 +583,35 @@ def create_task_from_xml(name, r''' Create a task based on XML. Source can be a file or a string of XML. - :param str name: The name of the task. This will be displayed in the task - scheduler. + Args: - :param str location: 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). + name (str): + The name of the task. This will be displayed in the task scheduler. - :param str xml_text: A string of xml representing the task to be created. - This will be overridden by `xml_path` if passed. + 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). - :param str xml_path: The path to an XML file on the local system containing - the xml that defines the task. This will override `xml_text` + xml_text (str): + A string of xml representing the task to be created. This will be + overridden by `xml_path` if passed. - :param str user_name: The user account under which to run the task. To - specify the 'System' account, use 'System'. The password will be - ignored. + 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` - :param str password: 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. + user_name (str): + The user account under which to run the task. To specify the + 'System' account, use 'System'. The password will be ignored. - :return: True if successful, False if unsuccessful - :rtype: bool + 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: + bool: ``True`` if successful, otherwise ``False`` CLI Example: @@ -631,7 +673,7 @@ def create_task_from_xml(name, except KeyError: failure_code = 'Unknown Failure: {0}'.format(error) - log.debug('Failed to create task: %s', failure_code) + log.debug('Failed to create task: {0}'.format(failure_code)) # Verify creation if name in list_tasks(location): @@ -644,15 +686,19 @@ def create_folder(name, location='\\'): r''' Create a folder in which to create tasks. - :param str name: The name of the folder. This will be displayed in the task - scheduler. + Args: - :param str location: 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). + name (str): + The name of the folder. This will be displayed in the task + scheduler. - :return: True if successful, False if unsuccessful - :rtype: bool + 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: + bool: ``True`` if successful, otherwise ``False`` CLI Example: @@ -714,148 +760,167 @@ def edit_task(name=None, r''' Edit the parameters of a task. Triggers and Actions cannot be edited yet. - :param str name: The name of the task. This will be displayed in the task - scheduler. - - :param str location: 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). - - :param str user_name: The user account under which to run the task. To - specify the 'System' account, use 'System'. The password will be - ignored. - - :param str password: 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. - - :param str description: A string representing the text that will be - displayed in the description field in the task scheduler. - - :param bool enabled: A boolean value representing whether or not the task is - enabled. - - :param bool hidden: A boolean value representing whether or not the task is - hidden. - - :param bool run_if_idle: Boolean value that indicates that the Task - Scheduler will run the task only if the computer is in an idle state. - - :param str idle_duration: 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 - - :param str idle_wait_timeout: 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 - - :param bool idle_stop_on_end: Boolean value that indicates that the Task - Scheduler will terminate the task if the idle condition ends before the - task is completed. - - :param bool idle_restart: Boolean value that indicates whether the task is - restarted when the computer cycles into an idle condition more than - once. - - :param bool ac_only: Boolean value that indicates that the Task Scheduler - will launch the task only while on AC power. - - :param bool stop_if_on_batteries: Boolean value that indicates that the task - will be stopped if the computer begins to run on battery power. - - :param bool wake_to_run: Boolean value that indicates that the Task - Scheduler will wake the computer when it is time to run the task. - - :param bool run_if_network: Boolean value that indicates that the Task - Scheduler will run the task only when a network is available. - - :param guid network_id: GUID value that identifies a network profile. - - :param str network_name: Sets the name of a network profile. The name is - used for display purposes. - - :param bool allow_demand_start: Boolean value that indicates that the task - can be started by using either the Run command or the Context menu. - - :param bool start_when_available: Boolean value that indicates that the Task - Scheduler can start the task at any time after its scheduled time has - passed. - - :param 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 - - :param int restart_count: The number of times the Task Scheduler will - attempt to restart the task. Valid values are integers 1 - 999. - - :param 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 - - :param bool force_stop: Boolean value that indicates that the task may be - terminated by using TerminateProcess. - - :param 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 - - :param str multiple_instances: 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 - - :return: True if successful, False if unsuccessful - :rtype: bool + Args: + + 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: + bool: ``True`` if successful, otherwise ``False`` CLI Example: @@ -1027,14 +1092,17 @@ def delete_task(name, location='\\'): r''' Delete a task from the task scheduler. - :param str name: The name of the task to delete. + Args: + name (str): + The name of the task to delete. - :param str location: A string value representing the location of the task. - Default is '\\' which is the root for the task scheduler - (C:\Windows\System32\tasks). + 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). - :return: True if successful, False if unsuccessful - :rtype: bool + Returns: + bool: ``True`` if successful, otherwise ``False`` CLI Example: @@ -1067,14 +1135,18 @@ def delete_folder(name, location='\\'): r''' Delete a folder from the task scheduler. - :param str name: The name of the folder to delete. + Args: - :param str location: A string value representing the location of the - folder. Default is '\\' which is the root for the task scheduler - (C:\Windows\System32\tasks). + name (str): + The name of the folder to delete. - :return: True if successful, False if unsuccessful - :rtype: bool + 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: + bool: ``True`` if successful, otherwise ``False`` CLI Example: @@ -1108,14 +1180,18 @@ def run(name, location='\\'): r''' Run a scheduled task manually. - :param str name: The name of the task to run. + Args: - :param str location: A string value representing the location of the task. - Default is '\\' which is the root for the task scheduler - (C:\Windows\System32\tasks). + name (str): + The name of the task to run. - :return: True if successful, False if unsuccessful - :rtype: bool + 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: + bool: ``True`` if successful, otherwise ``False`` CLI Example: @@ -1147,14 +1223,18 @@ def run_wait(name, location='\\'): r''' Run a scheduled task and return when the task finishes - :param str name: The name of the task to run. + Args: - :param str location: A string value representing the location of the task. - Default is '\\' which is the root for the task scheduler - (C:\Windows\System32\tasks). + name (str): + The name of the task to run. - :return: True if successful, False if unsuccessful - :rtype: bool + 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: + bool: ``True`` if successful, otherwise ``False`` CLI Example: @@ -1204,14 +1284,18 @@ def stop(name, location='\\'): r''' Stop a scheduled task. - :param str name: The name of the task to stop. + Args: - :param str location: A string value representing the location of the task. - Default is '\\' which is the root for the task scheduler - (C:\Windows\System32\tasks). + name (str): + The name of the task to stop. - :return: True if successful, False if unsuccessful - :rtype: bool + 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: + bool: ``True`` if successful, otherwise ``False`` CLI Example: @@ -1243,21 +1327,24 @@ def status(name, location='\\'): r''' Determine the status of a task. Is it Running, Queued, Ready, etc. - :param str name: The name of the task for which to return the status + Args: - :param str location: A string value representing the location of the task. - Default is '\\' which is the root for the task scheduler - (C:\Windows\System32\tasks). + name (str): + The name of the task for which to return the status - :return: The current status of the task. Will be one of the following: + 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). - - Unknown - - Disabled - - Queued - - Ready - - Running + Returns: + str: The current status of the task. Will be one of the following: - :rtype: string + - Unknown + - Disabled + - Queued + - Ready + - Running CLI Example: @@ -1285,14 +1372,18 @@ def info(name, location='\\'): r''' Get the details about a task in the task scheduler. - :param str name: The name of the task for which to return the status + Args: - :param str location: A string value representing the location of the task. - Default is '\\' which is the root for the task scheduler - (C:\Windows\System32\tasks). + 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). - :return: - :rtype: dict + Returns: + dict: A dictionary containing the task configuration CLI Example: @@ -1423,64 +1514,91 @@ def add_action(name=None, r''' Add an action to a task. - :param str name: The name of the task to which to add the action. + Args: - :param str location: A string value representing the location of the task. - Default is '\\' which is the root for the task scheduler - (C:\Windows\System32\tasks). + name (str): + The name of the task to which to add the action. - :param str action_type: The type of action to add. There are three action - types. Each one requires its own set of Keyword Arguments (kwargs). Valid - values are: + 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). - - Execute - - Email - - Message + 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 - :param str cmd: (required) The command / executable to run. + cmd (str): + (required) The command / executable to run. - :param str arguments: (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: + 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'`` + - ``cmd='cscript.exe' arguments='c:\scripts\myscript.vbs'`` - Batch files do not need an interpreter and may be passed to the cmd - parameter directly. + Batch files do not need an interpreter and may be passed to the cmd + parameter directly. - :param str start_in: (optional) The current working directory for the - command. + start_in (str): + (optional) The current working directory for the command. **Email** - Send and email. Requires ``server``, ``from``, and ``to`` or ``cc``. - :param str from: The sender - :param str reply_to: Who to reply to - :param str to: The recipient - :param str cc: The CC recipient - :param str bcc: The BCC recipient - :param str subject: The subject of the email - :param str body: The Message Body of the email - :param str server: The server used to send the email - :param list attachments: A list of attachments. These will be the paths to - the files to attach. ie: ``attachments="['C:\attachment1.txt', - 'C:\attachment2.txt']"`` + 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. - :param str title: The dialog box title. - :param str message: The dialog box message body + title (str): + The dialog box title. - :return: True if successful, False if unsuccessful - :rtype: bool + message (str): + The dialog box message body + + Returns: + dict: A dictionary containing the task configuration CLI Example: @@ -1591,7 +1709,7 @@ def _clear_actions(name, location='\\'): :param str name: The name of the task from which to clear all actions. :param str location: A string value representing the location of the task. - Default is '\\' which is the root for the task scheduler + Default is '\' which is the root for the task scheduler (C:\Windows\System32\tasks). :return: True if successful, False if unsuccessful @@ -1644,125 +1762,156 @@ def add_trigger(name=None, delay=None, **kwargs): r''' - :param str name: The name of the task to which to add the trigger. - - :param str location: A string value representing the location of the task. - Default is '\\' which is the root for the task scheduler - (C:\Windows\System32\tasks). - - :param str trigger_type: 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 - - :param bool trigger_enabled: Boolean value that indicates whether the - trigger is enabled. - - :param str start_date: 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 - - :param str start_time: 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 - - :param str end_date: 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 - - :param str end_time: 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 - - :param str random_delay: 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 - - :param str repeat_interval: The amount of time between each restart of the - task. Valid values are: - - - 5 minutes - - 10 minutes - - 15 minutes - - 30 minutes - - 1 hour - - :param str repeat_duration: How long the pattern is repeated. Valid values - are: - - - Indefinitely - - 15 minutes - - 30 minutes - - 1 hour - - 12 hours - - 1 day - - :param bool repeat_stop_at_duration_end: Boolean value that indicates if a - running instance of the task is stopped at the end of the repetition - pattern duration. - - :param str execution_time_limit: 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) - - :param str delay: 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 + Add a trigger to a Windows Scheduled task + + Args: + + 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 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 + + 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** @@ -1771,9 +1920,10 @@ def add_trigger(name=None, *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. + 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* @@ -1781,61 +1931,69 @@ def add_trigger(name=None, *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. - + 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* - :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. + 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. + 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* - :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. + 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. - :param list days_of_month: 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. + 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. - :param bool last_day_of_month: Boolean value that indicates that the - task runs on the last day of the month regardless of the actual date of - that day. + 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. + .. 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* - :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. + 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. - :param list weeks_of_month: Sets the weeks of the month during which the - task runs. Should be a list. ie: ['First','Third']. Valid options are: + 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 + - First + - Second + - Third + - Fourth - :param bool last_week_of_month: Boolean value that indicates that the task - runs on the last week of the month. + last_week_of_month (bool): + Boolean value that indicates that the task runs on the last week of + the month. - :param list days_of_week: 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. + 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. @@ -1851,38 +2009,38 @@ def add_trigger(name=None, *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. - - :param str state_change: Sets the kind of Terminal Server session change - that would trigger a task launch. Valid options are: + 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. - - 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 + state_change (str): + Sets the kind of Terminal Server session change that would trigger a + task launch. Valid options are: - .. note:: + - 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 - 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. + .. note:: - .. _`YAML IDIOSYNCRASIES`: https://docs.saltstack.com/en/latest/topics/troubleshooting/yaml_idiosyncrasies.html#time-expressions + 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. + .. _`YAML IDIOSYNCRASIES`: https://docs.saltstack.com/en/latest/topics/troubleshooting/yaml_idiosyncrasies.html#time-expressions - :return: True if successful, False if unsuccessful - :rtype: bool + Returns: + bool: ``True`` if successful, otherwise ``False`` CLI Example: .. code-block:: bash - salt 'minion-id' task.add_trigger trigger_type=Once trigger_enabled=True start_date=2016/12/1 start_time='"12:01"' + salt 'minion-id' task.add_trigger trigger_type=Once trigger_enabled=True start_date=2016/12/1 start_time=12:01 ''' if not trigger_type: return 'Required parameter "trigger_type" not specified' @@ -2171,14 +2329,18 @@ def clear_triggers(name, location='\\'): r''' Remove all triggers from the task. - :param str name: The name of the task from which to clear all triggers. + Args: - :param str location: A string value representing the location of the task. - Default is '\\' which is the root for the task scheduler - (C:\Windows\System32\tasks). + name (str): + The name of the task from which to clear all triggers. - :return: True if successful, False if unsuccessful - :rtype: bool + 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: + bool: ``True`` if successful, otherwise ``False`` CLI Example: From b6494950e616f324ce4aee7219874c64ac5ee368 Mon Sep 17 00:00:00 2001 From: twangboy Date: Mon, 15 Apr 2019 11:16:50 -0600 Subject: [PATCH 02/11] Honor 80 character line limit --- salt/modules/win_task.py | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/salt/modules/win_task.py b/salt/modules/win_task.py index d28d02909e3a..0e561da72145 100644 --- a/salt/modules/win_task.py +++ b/salt/modules/win_task.py @@ -2027,9 +2027,10 @@ def add_trigger(name=None, .. 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. + 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. .. _`YAML IDIOSYNCRASIES`: https://docs.saltstack.com/en/latest/topics/troubleshooting/yaml_idiosyncrasies.html#time-expressions From e01077bfc27e09eafb5b219dd9406ebe63da99e7 Mon Sep 17 00:00:00 2001 From: twangboy Date: Mon, 15 Apr 2019 13:02:55 -0600 Subject: [PATCH 03/11] Fix docs issue... maybe... --- salt/modules/win_task.py | 134 +++++++++++++++++++-------------------- 1 file changed, 64 insertions(+), 70 deletions(-) diff --git a/salt/modules/win_task.py b/salt/modules/win_task.py index 0e561da72145..31a509814966 100644 --- a/salt/modules/win_task.py +++ b/salt/modules/win_task.py @@ -325,8 +325,8 @@ def list_tasks(location='\\'): 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). + tasks. Default is ``\`` which is the root for the task scheduler + (``C:\Windows\System32\tasks``). Returns: list: Returns a list of tasks @@ -365,8 +365,8 @@ def list_folders(location='\\'): 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). + tasks. Default is ``\`` which is the root for the task scheduler + (``C:\Windows\System32\tasks``). Returns: list: Returns a list of folders. @@ -407,8 +407,8 @@ def list_triggers(name, location='\\'): 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). + from which to list triggers. Default is ``\`` which is the root for + the task scheduler (``C:\Windows\System32\tasks``). Returns: list: Returns a list of triggers. @@ -452,8 +452,8 @@ def list_actions(name, location='\\'): 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). + list actions. Default is ``\`` which is the root for the task + scheduler (``C:\Windows\System32\tasks``). Returns: list: Returns a list of actions. @@ -507,8 +507,8 @@ def create_task(name, 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). + 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 @@ -590,8 +590,8 @@ def create_task_from_xml(name, 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). + 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 @@ -694,8 +694,8 @@ def create_folder(name, location='\\'): 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). + folder. Default is ``\`` which is the root for the task scheduler + (``C:\Windows\System32\tasks``). Returns: bool: ``True`` if successful, otherwise ``False`` @@ -767,8 +767,8 @@ def edit_task(name=None, 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). + 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 @@ -1098,8 +1098,8 @@ def delete_task(name, location='\\'): 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). + ``\`` which is the root for the task scheduler + (``C:\Windows\System32\tasks``). Returns: bool: ``True`` if successful, otherwise ``False`` @@ -1142,8 +1142,8 @@ def delete_folder(name, location='\\'): 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). + ``\`` which is the root for the task scheduler + (``C:\Windows\System32\tasks``). Returns: bool: ``True`` if successful, otherwise ``False`` @@ -1186,9 +1186,9 @@ def run(name, location='\\'): The name of the task to run. location (str): - A string value representing the location of the task. Default is '\' + A string value representing the location of the task. Default is ``\`` which is the root for the task scheduler - (C:\Windows\System32\tasks). + (``C:\Windows\System32\tasks``). Returns: bool: ``True`` if successful, otherwise ``False`` @@ -1229,9 +1229,9 @@ def run_wait(name, location='\\'): 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). + A string value representing the location of the task. Default is + ``\`` which is the root for the task scheduler + (``C:\Windows\System32\tasks``). Returns: bool: ``True`` if successful, otherwise ``False`` @@ -1290,9 +1290,9 @@ def stop(name, location='\\'): 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). + A string value representing the location of the task. Default is + ``\`` which is the root for the task scheduler + (``C:\Windows\System32\tasks``). Returns: bool: ``True`` if successful, otherwise ``False`` @@ -1333,9 +1333,9 @@ def status(name, location='\\'): 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). + A string value representing the location of the task. Default is + ``\`` which is the root for the task scheduler + (``C:\Windows\System32\tasks``). Returns: str: The current status of the task. Will be one of the following: @@ -1378,9 +1378,9 @@ def info(name, location='\\'): 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). + A string value representing the location of the task. Default is + ``\`` which is the root for the task scheduler + (``C:\Windows\System32\tasks``). Returns: dict: A dictionary containing the task configuration @@ -1520,9 +1520,9 @@ def add_action(name=None, 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). + 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 @@ -1535,7 +1535,9 @@ def add_action(name=None, Required arguments for each action_type: - **Execute** - Execute a command or an executable + **Execute** + + Execute a command or an executable cmd (str): (required) The command / executable to run. @@ -1555,39 +1557,26 @@ def add_action(name=None, 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 + **Email** - 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 + 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 + **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. @@ -1709,8 +1698,8 @@ def _clear_actions(name, location='\\'): :param str name: The name of the task from which to clear all actions. :param str location: A string value representing the location of the task. - Default is '\' which is the root for the task scheduler - (C:\Windows\System32\tasks). + Default is ``\`` which is the root for the task scheduler + (``C:\Windows\System32\tasks``). :return: True if successful, False if unsuccessful :rtype: bool @@ -1771,8 +1760,8 @@ def add_trigger(name=None, 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). + ``\`` 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 @@ -1936,6 +1925,7 @@ def add_trigger(name=None, 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* weeks_interval (int): @@ -1996,15 +1986,19 @@ def add_trigger(name=None, 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* @@ -2336,9 +2330,9 @@ def clear_triggers(name, location='\\'): The name of the task from which to clear all triggers. location (str): - A string value representing the location of the task. Default is '\' + A string value representing the location of the task. Default is ``\`` which is the root for the task scheduler - (C:\Windows\System32\tasks). + (``C:\Windows\System32\tasks``). Returns: bool: ``True`` if successful, otherwise ``False`` From c691e0d1af8c9f41e32e7a5a63b840f188c010d6 Mon Sep 17 00:00:00 2001 From: twangboy Date: Mon, 15 Apr 2019 13:26:31 -0600 Subject: [PATCH 04/11] More doc fixes --- salt/modules/win_task.py | 262 +++++++++++++++++++-------------------- 1 file changed, 131 insertions(+), 131 deletions(-) diff --git a/salt/modules/win_task.py b/salt/modules/win_task.py index 31a509814966..289bbe9b24af 100644 --- a/salt/modules/win_task.py +++ b/salt/modules/win_task.py @@ -496,9 +496,9 @@ def create_task(name, Create a new task in the designated location. This function has many keyword arguments that are not listed here. For additional arguments see: - - :py:func:`edit_task` - - :py:func:`add_action` - - :py:func:`add_trigger` + - :py:func:`edit_task` + - :py:func:`add_action` + - :py:func:`add_trigger` Args: @@ -806,25 +806,25 @@ def edit_task(name=None, 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 + - 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 + - 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 @@ -869,14 +869,14 @@ def edit_task(name=None, 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 + - 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 @@ -885,14 +885,14 @@ def edit_task(name=None, 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 + - 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 @@ -903,21 +903,21 @@ def edit_task(name=None, 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 + - 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 + - Parallel + - Queue + - No New Instance + - Stop Existing Returns: bool: ``True`` if successful, otherwise ``False`` @@ -1529,9 +1529,9 @@ def add_action(name=None, requires its own set of Keyword Arguments (kwargs). Valid values are: - - Execute - - Email - - Message + - Execute + - Email + - Message Required arguments for each action_type: @@ -1549,7 +1549,7 @@ def add_action(name=None, ``cscript.exe`` in the `cmd` parameter and pass the script in the ``arguments`` parameter as follows: - - ``cmd='cscript.exe' arguments='c:\scripts\myscript.vbs'`` + - ``cmd='cscript.exe' arguments='c:\scripts\myscript.vbs'`` Batch files do not need an interpreter and may be passed to the cmd parameter directly. @@ -1767,17 +1767,17 @@ def add_trigger(name=None, 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 + - Event + - Once + - Daily + - Weekly + - Monthly + - MonthlyDay + - OnIdle + - OnTaskCreation + - OnBoot + - OnLogon + - OnSessionChange trigger_enabled (bool): Boolean value that indicates whether the trigger is enabled. @@ -1786,83 +1786,83 @@ def add_trigger(name=None, 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 + - %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 + - %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 + - %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 the this is not passed + 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 + - %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 + - 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 + - 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 + - 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 + - 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 @@ -1872,35 +1872,35 @@ def add_trigger(name=None, 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) + - 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 + - 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 + - OnLogon + - OnBoot + - Event + - OnTaskCreation + - OnSessionChange **kwargs** @@ -1971,10 +1971,10 @@ def add_trigger(name=None, 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 + - First + - Second + - Third + - Fourth last_week_of_month (bool): Boolean value that indicates that the task runs on the last week of @@ -2012,12 +2012,12 @@ def add_trigger(name=None, 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 + - 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:: From 18cfc158958478dec146fde53d1aefedbe2db1be Mon Sep 17 00:00:00 2001 From: twangboy Date: Mon, 15 Apr 2019 14:01:43 -0600 Subject: [PATCH 05/11] Fix docs... attempt 3 --- salt/modules/win_task.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/salt/modules/win_task.py b/salt/modules/win_task.py index 289bbe9b24af..b546488799ec 100644 --- a/salt/modules/win_task.py +++ b/salt/modules/win_task.py @@ -1804,8 +1804,7 @@ def add_trigger(name=None, 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: + the task after it is deactivated. Can be one of the following formats: - %Y-%m-%d - %m-%d-%y @@ -2251,11 +2250,12 @@ def add_trigger(name=None, trigger.DaysOfMonth = bits_days trigger.RunOnLastDayOfMonth = kwargs.get('last_day_of_month', False) else: - return 'Monthly trigger requires "days_of_month" or "last_day_of_month" parameters' + return 'Monthly trigger requires "days_of_month" or "last_day_of_' \ + 'month" parameters' # Monthly Day Of Week Trigger Parameters elif trigger_types[trigger_type] == TASK_TRIGGER_MONTHLYDOW: - trigger.Id = 'Monthy_DOW_ID1' + trigger.Id = 'Monthly_DOW_ID1' if kwargs.get('months_of_year', False): bits_months = 0 for month in kwargs.get('months_of_year'): From f6f33812d2cf1c391be53d46283818bec03f93c3 Mon Sep 17 00:00:00 2001 From: twangboy Date: Mon, 15 Apr 2019 14:31:14 -0600 Subject: [PATCH 06/11] Fix docs... attempt 4 --- salt/modules/win_task.py | 102 +++++++++++++++++++++++---------------- 1 file changed, 61 insertions(+), 41 deletions(-) diff --git a/salt/modules/win_task.py b/salt/modules/win_task.py index b546488799ec..335719212a9b 100644 --- a/salt/modules/win_task.py +++ b/salt/modules/win_task.py @@ -155,7 +155,8 @@ 0x41306: 'Task was terminated by the user', 0x8004130F: 'Credentials became corrupted', 0x8004131F: 'An instance of this task is already running', - 0x800704DD: 'The service is not available (Run only when logged in?)', + 0x800704DD: 'The service is not available (Run only when logged ' + 'in?)', 0x800710E0: 'The operator or administrator has refused the request', 0xC000013A: 'The application terminated as a result of CTRL+C', 0xC06D007E: 'Unknown software exception'} @@ -169,7 +170,7 @@ def __virtual__(): if not HAS_DEPENDENCIES: log.warning('Could not load dependencies for %s', __virtualname__) return __virtualname__ - return (False, "Module win_task: module only works on Windows systems") + return False, 'Module win_task: module only works on Windows systems' def _get_date_time_format(dt_string): @@ -302,7 +303,8 @@ def _save_task_definition(name, except pythoncom.com_error as error: hr, msg, exc, arg = error.args # pylint: disable=W0633 - fc = {-2147024773: 'The filename, directory name, or volume label syntax is incorrect', + fc = {-2147024773: 'The filename, directory name, or volume label ' + 'syntax is incorrect', -2147024894: 'The system cannot find the file specified', -2147216615: 'Required element or attribute missing', -2147216616: 'Value incorrectly formatted or out of range', @@ -422,7 +424,7 @@ def list_triggers(name, location='\\'): # List all triggers for the XblGameSaveTask in the Microsoft\XblGameSave # location - salt 'minion-id' task.list_triggers XblGameSaveTask Microsoft\XblGameSave + salt '*' task.list_triggers XblGameSaveTask Microsoft\XblGameSave ''' # Create the task service object with salt.utils.winapi.Com(): @@ -617,7 +619,7 @@ def create_task_from_xml(name, .. code-block:: bash - salt 'minion-id' task.create_task_from_xml xml_path=C:\task.xml + salt '*' task.create_task_from_xml xml_path=C:\task.xml ''' # Check for existing task if name in list_tasks(location): @@ -780,6 +782,7 @@ def edit_task(name=None, 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 @@ -926,7 +929,7 @@ def edit_task(name=None, .. code-block:: bash - salt 'minion-id' task.edit_task description='This task is awesome' + salt '*' task.edit_task description='This task is awesome' ''' # TODO: Add more detailed return for items changed @@ -1047,7 +1050,8 @@ def edit_task(name=None, task_definition.Settings.RestartInterval = '' else: if restart_every in duration: - task_definition.Settings.RestartInterval = _lookup_first(duration, restart_every) + task_definition.Settings.RestartInterval = _lookup_first( + duration, restart_every) else: return 'Invalid value for "restart_every"' if task_definition.Settings.RestartInterval: @@ -1061,7 +1065,8 @@ def edit_task(name=None, task_definition.Settings.ExecutionTimeLimit = 'PT0S' else: if execution_time_limit in duration: - task_definition.Settings.ExecutionTimeLimit = _lookup_first(duration, execution_time_limit) + task_definition.Settings.ExecutionTimeLimit = _lookup_first( + duration, execution_time_limit) else: return 'Invalid value for "execution_time_limit"' if force_stop is not None: @@ -1071,7 +1076,8 @@ def edit_task(name=None, if delete_after is False: task_definition.Settings.DeleteExpiredTaskAfter = '' if delete_after in duration: - task_definition.Settings.DeleteExpiredTaskAfter = _lookup_first(duration, delete_after) + task_definition.Settings.DeleteExpiredTaskAfter = _lookup_first( + duration, delete_after) else: return 'Invalid value for "delete_after"' if multiple_instances is not None: @@ -1186,8 +1192,8 @@ def run(name, location='\\'): 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 + A string value representing the location of the task. Default is + ``\`` which is the root for the task scheduler (``C:\Windows\System32\tasks``). Returns: @@ -1215,7 +1221,7 @@ def run(name, location='\\'): try: task.Run('') return True - except pythoncom.com_error as error: + except pythoncom.com_error: return False @@ -1319,7 +1325,7 @@ def stop(name, location='\\'): try: task.Stop(0) return True - except pythoncom.com_error as error: + except pythoncom.com_error: return False @@ -1413,39 +1419,43 @@ def info(name, location='\\'): def_set = task.Definition.Settings - settings = {} - settings['allow_demand_start'] = def_set.AllowDemandStart - settings['force_stop'] = def_set.AllowHardTerminate + settings = { + 'allow_demand_start': def_set.AllowDemandStart, + 'force_stop': def_set.AllowHardTerminate} if def_set.DeleteExpiredTaskAfter == '': settings['delete_after'] = False elif def_set.DeleteExpiredTaskAfter == 'PT0S': settings['delete_after'] = 'Immediately' else: - settings['delete_after'] = _reverse_lookup(duration, def_set.DeleteExpiredTaskAfter) + settings['delete_after'] = _reverse_lookup( + duration, def_set.DeleteExpiredTaskAfter) if def_set.ExecutionTimeLimit == '': settings['execution_time_limit'] = False else: - settings['execution_time_limit'] = _reverse_lookup(duration, def_set.ExecutionTimeLimit) + settings['execution_time_limit'] = _reverse_lookup( + duration, def_set.ExecutionTimeLimit) - settings['multiple_instances'] = _reverse_lookup(instances, def_set.MultipleInstances) + settings['multiple_instances'] = _reverse_lookup( + instances, def_set.MultipleInstances) if def_set.RestartInterval == '': settings['restart_interval'] = False else: - settings['restart_interval'] = _reverse_lookup(duration, def_set.RestartInterval) + settings['restart_interval'] = _reverse_lookup( + duration, def_set.RestartInterval) if settings['restart_interval']: settings['restart_count'] = def_set.RestartCount settings['stop_if_on_batteries'] = def_set.StopIfGoingOnBatteries settings['wake_to_run'] = def_set.WakeToRun - conditions = {} - conditions['ac_only'] = def_set.DisallowStartIfOnBatteries - conditions['run_if_idle'] = def_set.RunOnlyIfIdle - conditions['run_if_network'] = def_set.RunOnlyIfNetworkAvailable - conditions['start_when_available'] = def_set.StartWhenAvailable + conditions = { + 'ac_only': def_set.DisallowStartIfOnBatteries, + 'run_if_idle': def_set.RunOnlyIfIdle, + 'run_if_network': def_set.RunOnlyIfNetworkAvailable, + 'start_when_available': def_set.StartWhenAvailable} if conditions['run_if_idle']: idle_set = def_set.IdleSettings @@ -1461,8 +1471,7 @@ def info(name, location='\\'): actions = [] for actionObj in task.Definition.Actions: - action = {} - action['action_type'] = _reverse_lookup(action_types, actionObj.Type) + action = {'action_type': _reverse_lookup(action_types, actionObj.Type)} if actionObj.Path: action['cmd'] = actionObj.Path if actionObj.Arguments: @@ -1473,10 +1482,11 @@ def info(name, location='\\'): triggers = [] for triggerObj in task.Definition.Triggers: - trigger = {} - trigger['trigger_type'] = _reverse_lookup(trigger_types, triggerObj.Type) + trigger = { + 'trigger_type': _reverse_lookup(trigger_types, triggerObj.Type)} if triggerObj.ExecutionTimeLimit: - trigger['execution_time_limit'] = _reverse_lookup(duration, triggerObj.ExecutionTimeLimit) + trigger['execution_time_limit'] = _reverse_lookup( + duration, triggerObj.ExecutionTimeLimit) if triggerObj.StartBoundary: start_date, start_time = triggerObj.StartBoundary.split('T', 1) trigger['start_date'] = start_date @@ -1488,7 +1498,8 @@ def info(name, location='\\'): trigger['enabled'] = triggerObj.Enabled if hasattr(triggerObj, 'RandomDelay'): if triggerObj.RandomDelay: - trigger['random_delay'] = _reverse_lookup(duration, triggerObj.RandomDelay) + trigger['random_delay'] = _reverse_lookup( + duration, triggerObj.RandomDelay) else: trigger['random_delay'] = False if hasattr(triggerObj, 'Delay'): @@ -1804,7 +1815,8 @@ def add_trigger(name=None, 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: + the task after it is deactivated. Can be one of the following + formats: - %Y-%m-%d - %m-%d-%y @@ -1835,6 +1847,7 @@ def add_trigger(name=None, - 1 day .. note:: + This parameter applies to the following trigger types - Once @@ -1893,6 +1906,7 @@ def add_trigger(name=None, - 1 day .. note:: + This parameter applies to the following trigger types: - OnLogon @@ -1955,6 +1969,7 @@ def add_trigger(name=None, 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. @@ -2011,8 +2026,10 @@ def add_trigger(name=None, 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) + - 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 @@ -2129,7 +2146,6 @@ def add_trigger(name=None, tm_obj.strftime('%H:%M:%S')) dt_obj = None - tm_obj = None if end_date: date_format = _get_date_time_format(end_date) if date_format: @@ -2192,10 +2208,12 @@ def add_trigger(name=None, if repeat_interval: trigger.Repetition.Interval = _lookup_first(duration, repeat_interval) if repeat_duration: - trigger.Repetition.Duration = _lookup_first(duration, repeat_duration) + trigger.Repetition.Duration = _lookup_first(duration, + repeat_duration) trigger.Repetition.StopAtDurationEnd = repeat_stop_at_duration_end if execution_time_limit: - trigger.ExecutionTimeLimit = _lookup_first(duration, execution_time_limit) + trigger.ExecutionTimeLimit = _lookup_first(duration, + execution_time_limit) if end_boundary: trigger.EndBoundary = end_boundary trigger.Enabled = trigger_enabled @@ -2271,9 +2289,11 @@ def add_trigger(name=None, for week in kwargs.get('weeks_of_month'): bits_weeks |= weeks[week] trigger.WeeksOfMonth = bits_weeks - trigger.RunOnLastWeekOfMonth = kwargs.get('last_week_of_month', False) + trigger.RunOnLastWeekOfMonth = kwargs.get('last_week_of_month', + False) else: - return 'Monthly DOW trigger requires "weeks_of_month" or "last_week_of_month" parameters' + return 'Monthly DOW trigger requires "weeks_of_month" or "last_' \ + 'week_of_month" parameters' if kwargs.get('days_of_week', False): bits_days = 0 @@ -2330,8 +2350,8 @@ def clear_triggers(name, location='\\'): 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 + A string value representing the location of the task. Default is + ``\`` which is the root for the task scheduler (``C:\Windows\System32\tasks``). Returns: From a66716ebc5213c3cf3ccc2c471b722a1e16c9ff9 Mon Sep 17 00:00:00 2001 From: twangboy Date: Mon, 15 Apr 2019 14:55:12 -0600 Subject: [PATCH 07/11] Fix docs... attempt 5 --- salt/modules/win_task.py | 239 +++++++++++++++++++++------------------ 1 file changed, 127 insertions(+), 112 deletions(-) diff --git a/salt/modules/win_task.py b/salt/modules/win_task.py index 335719212a9b..5116cde4bfa6 100644 --- a/salt/modules/win_task.py +++ b/salt/modules/win_task.py @@ -1548,54 +1548,54 @@ def add_action(name=None, **Execute** - Execute a command or an executable + Execute a command or an executable - cmd (str): - (required) The command / executable to run. + cmd (str): + (required) The command or 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: + 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'`` + - ``cmd='cscript.exe' arguments='c:\scripts\myscript.vbs'`` - Batch files do not need an interpreter and may be passed to the cmd - parameter directly. + 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. + 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']"`` + 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. + 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. + title (str): + The dialog box title. - message (str): - The dialog box message body + message (str): + The dialog box message body Returns: dict: A dictionary containing the task configuration @@ -1922,127 +1922,142 @@ def add_trigger(name=None, *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. + 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. + No special parameters required. *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. + 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* - 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. + The task will run weekly. - 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. + 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* - 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. + 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. + 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. + 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:: + .. 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. + 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* - 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. + The task will run monthly an the specified day. - 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: + 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. - - First - - Second - - Third - - Fourth + 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: - last_week_of_month (bool): - Boolean value that indicates that the task runs on the last week of - the month. + - First + - Second + - Third + - Fourth - 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. + 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. + No special parameters required. *OnTaskCreation* - No special parameters required. + No special parameters required. *OnBoot* - No special parameters required. + No special parameters required. *OnLogon* - No special parameters required. + No special parameters required. *OnSessionChange* - 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. + The task will be triggered by a session change. - state_change (str): - Sets the kind of Terminal Server session change that would trigger a - task launch. Valid options are: + 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. - - 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 + state_change (str): + Sets the kind of Terminal Server session change that would + trigger a task launch. Valid options are: - .. note:: + - 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. + 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. - .. _`YAML IDIOSYNCRASIES`: https://docs.saltstack.com/en/latest/topics/troubleshooting/yaml_idiosyncrasies.html#time-expressions + .. _`YAML IDIOSYNCRASIES`: https://docs.saltstack.com/en/latest/topics/troubleshooting/yaml_idiosyncrasies.html#time-expressions Returns: bool: ``True`` if successful, otherwise ``False`` From 58f0cd2b86c5a40c197714da7ce7753bf3c4d213 Mon Sep 17 00:00:00 2001 From: twangboy Date: Mon, 15 Apr 2019 15:04:53 -0600 Subject: [PATCH 08/11] Fix docs... attempt 6 --- salt/modules/win_task.py | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/salt/modules/win_task.py b/salt/modules/win_task.py index 5116cde4bfa6..1619db3b9c46 100644 --- a/salt/modules/win_task.py +++ b/salt/modules/win_task.py @@ -1573,13 +1573,21 @@ def add_action(name=None, 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', From a279d458439182dca29cc3e0ab2f0a859eec2b68 Mon Sep 17 00:00:00 2001 From: twangboy Date: Mon, 15 Apr 2019 16:31:20 -0600 Subject: [PATCH 09/11] Final doc fixes --- salt/modules/win_task.py | 37 +++++++++++++++++++------------------ 1 file changed, 19 insertions(+), 18 deletions(-) diff --git a/salt/modules/win_task.py b/salt/modules/win_task.py index 1619db3b9c46..7e39a87c1824 100644 --- a/salt/modules/win_task.py +++ b/salt/modules/win_task.py @@ -365,10 +365,10 @@ def list_folders(location='\\'): Args: - 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``). + 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: list: Returns a list of folders. @@ -408,9 +408,10 @@ def list_triggers(name, location='\\'): 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``). + 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: list: Returns a list of triggers. @@ -675,7 +676,7 @@ def create_task_from_xml(name, except KeyError: failure_code = 'Unknown Failure: {0}'.format(error) - log.debug('Failed to create task: {0}'.format(failure_code)) + log.debug('Failed to create task: %s', failure_code) # Verify creation if name in list_tasks(location): @@ -1772,6 +1773,15 @@ def add_trigger(name=None, r''' 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. + + .. _`YAML IDIOSYNCRASIES`: https://docs.saltstack.com/en/latest/topics/troubleshooting/yaml_idiosyncrasies.html#time-expressions + Args: name (str): @@ -2058,15 +2068,6 @@ def add_trigger(name=None, - 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. - - .. _`YAML IDIOSYNCRASIES`: https://docs.saltstack.com/en/latest/topics/troubleshooting/yaml_idiosyncrasies.html#time-expressions - Returns: bool: ``True`` if successful, otherwise ``False`` @@ -2074,7 +2075,7 @@ def add_trigger(name=None, .. code-block:: bash - salt 'minion-id' task.add_trigger trigger_type=Once trigger_enabled=True start_date=2016/12/1 start_time=12:01 + salt 'minion-id' task.add_trigger trigger_type=Once trigger_enabled=True start_date=2016/12/1 start_time='"12:01"' ''' if not trigger_type: return 'Required parameter "trigger_type" not specified' From deb0b10bb41938c4c5cffb1a16805cc6e6cd37dd Mon Sep 17 00:00:00 2001 From: twangboy Date: Mon, 15 Apr 2019 16:41:04 -0600 Subject: [PATCH 10/11] Fix some lint --- salt/modules/win_task.py | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/salt/modules/win_task.py b/salt/modules/win_task.py index 7e39a87c1824..cef1e73b4ebf 100644 --- a/salt/modules/win_task.py +++ b/salt/modules/win_task.py @@ -1960,7 +1960,7 @@ def add_trigger(name=None, 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. @@ -2029,19 +2029,19 @@ def add_trigger(name=None, 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* From fd19cca2f6c0105996b651e2488b549aeb0a48b0 Mon Sep 17 00:00:00 2001 From: twangboy Date: Tue, 16 Apr 2019 11:10:58 -0600 Subject: [PATCH 11/11] Remove some warts in the docs --- salt/modules/win_task.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/salt/modules/win_task.py b/salt/modules/win_task.py index cef1e73b4ebf..4f7e7a5c5d93 100644 --- a/salt/modules/win_task.py +++ b/salt/modules/win_task.py @@ -598,11 +598,11 @@ def create_task_from_xml(name, xml_text (str): A string of xml representing the task to be created. This will be - overridden by `xml_path` if passed. + 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` + defines the task. This will override ``xml_text`` user_name (str): The user account under which to run the task. To specify the @@ -1558,7 +1558,7 @@ def add_action(name=None, (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 + 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'`` @@ -1999,7 +1999,7 @@ def add_trigger(name=None, 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``. + setting the parameter 'last_day_of_month' equal to ``True``. *MonthlyDay*