mirror of https://github.com/ansible/ansible.git
win_scheduled_task_stat: add new module to get stat on scheduled tasks (#30602)
* win_scheduled_task_stat: add new module to get stat on scheduled tasks * fixed up linting errors and aliases file * I should learn how to spell * removing URI from test * added state information for the task * removed argument so task stays runningpull/30696/merge
parent
0e9ae5b8cc
commit
59187358ee
@ -0,0 +1,367 @@
|
||||
#!/usr/bin/python
|
||||
# -*- coding: utf-8 -*-
|
||||
|
||||
# Copyright (c) 2017 Ansible Project
|
||||
# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
|
||||
|
||||
# this is a windows documentation stub. actual code lives in the .ps1
|
||||
# file of the same name
|
||||
|
||||
ANSIBLE_METADATA = {'metadata_version': '1.1',
|
||||
'status': ['preview'],
|
||||
'supported_by': 'community'}
|
||||
|
||||
|
||||
DOCUMENTATION = r'''
|
||||
---
|
||||
module: win_scheduled_task_stat
|
||||
version_added: "2.5"
|
||||
short_description: Returns information about a Windows Scheduled Task
|
||||
description:
|
||||
- Will return whether the folder and task exists.
|
||||
- Returns the names of tasks in the folder specified.
|
||||
- If C(name) is set and exists, will return information on the task itself.
|
||||
- Use M(win_scheduled_task) to configure a scheduled task.
|
||||
options:
|
||||
path:
|
||||
description: The folder path where the task lives.
|
||||
default: \
|
||||
name:
|
||||
description: The name of the scheduled task to get information for.
|
||||
author:
|
||||
- Jordan Borean (@jborean93)
|
||||
'''
|
||||
|
||||
EXAMPLES = r'''
|
||||
- name: get information about a folder
|
||||
win_scheduled_task_stat:
|
||||
path: \folder name
|
||||
register: task_folder_stat
|
||||
|
||||
- name: get information about a task in the root folder
|
||||
win_scheduled_task_stat:
|
||||
name: task name
|
||||
register: task_stat
|
||||
|
||||
- name: get information about a task in a custom folder
|
||||
win_scheduled_task_stat:
|
||||
path: \folder name
|
||||
name: task name
|
||||
register: task_stat
|
||||
'''
|
||||
|
||||
RETURN = r'''
|
||||
actions:
|
||||
description: A list of actions.
|
||||
returned: name is specified and task exists
|
||||
type: list
|
||||
sample: [
|
||||
{
|
||||
"Arguments": "/c echo hi",
|
||||
"Id": null,
|
||||
"Path": "cmd.exe",
|
||||
"Type": "TASK_ACTION_EXEC",
|
||||
"WorkingDirectory": null
|
||||
}
|
||||
]
|
||||
folder_exists:
|
||||
description: Whether the folder set at path exists.
|
||||
returned: always
|
||||
type: boolean
|
||||
sample: True
|
||||
folder_task_count:
|
||||
description: The number of tasks that exist in the folder.
|
||||
returned: always
|
||||
type: int
|
||||
sample: 2
|
||||
folder_task_names:
|
||||
description: A list of tasks that exist in the folder.
|
||||
returned: always
|
||||
type: list
|
||||
sample: [ 'Task 1', 'Task 2' ]
|
||||
principal:
|
||||
description: Details on the principal configured to run the task.
|
||||
returned: name is specified and task exists
|
||||
type: complex
|
||||
contains:
|
||||
display_name:
|
||||
description: The name of the user/group that is displayed in the Task
|
||||
Scheduler UI.
|
||||
returned: ''
|
||||
type: str
|
||||
sample: Administrator
|
||||
group_id:
|
||||
description: The group that will run the task.
|
||||
returned: ''
|
||||
type: str
|
||||
sample: BUILTIN\Administrators
|
||||
id:
|
||||
description: The ID for the principal.
|
||||
returned: ''
|
||||
type: str
|
||||
sample: Author
|
||||
logon_type:
|
||||
description: The logon method that the task will run with.
|
||||
returned: ''
|
||||
type: str
|
||||
sample: TASK_LOGON_INTERACTIVE_TOKEN
|
||||
run_level:
|
||||
description: The level of user rights used to run the task.
|
||||
returned: ''
|
||||
type: str
|
||||
sample: TASK_RUNLEVEL_LUA
|
||||
user_id:
|
||||
description: The user that will run the task.
|
||||
returned: ''
|
||||
type: str
|
||||
sample: SERVER\Administrator
|
||||
registration_info:
|
||||
description: Details on the task registration info.
|
||||
returned: name is specified and task exists
|
||||
type: complex
|
||||
contains:
|
||||
author:
|
||||
description: The author os the task.
|
||||
returned: ''
|
||||
type: str
|
||||
sample: SERVER\Administrator
|
||||
date:
|
||||
description: The date when the task was register.
|
||||
returned: ''
|
||||
type: str
|
||||
sample: '2017-01-01T10:00:00'
|
||||
description:
|
||||
description: The description of the task.
|
||||
returned: ''
|
||||
type: str
|
||||
sample: task description
|
||||
documentation:
|
||||
description: The documentation of the task.
|
||||
returned: ''
|
||||
type: str
|
||||
sample: task documentation
|
||||
security_descriptor:
|
||||
description: The security descriptor of the task.
|
||||
returned: ''
|
||||
type: str
|
||||
sample: security descriptor
|
||||
source:
|
||||
description: The source of the task.
|
||||
returned: ''
|
||||
type: str
|
||||
sample: source
|
||||
uri:
|
||||
description: The URI/path of the task.
|
||||
returned: ''
|
||||
type: str
|
||||
sample: \task\task name
|
||||
version:
|
||||
description: The version of the task.
|
||||
returned: ''
|
||||
type: str
|
||||
sample: 1.0
|
||||
settings:
|
||||
description: Details on the task settings.
|
||||
returned: name is specified and task exists
|
||||
type: complex
|
||||
contains:
|
||||
allow_demand_start:
|
||||
description: Whether the task can be started by using either the Run
|
||||
command of the Context menu.
|
||||
returned: ''
|
||||
type: bool
|
||||
sample: True
|
||||
allow_hard_terminate:
|
||||
description: Whether the task can terminated by using TerminateProcess.
|
||||
returned: ''
|
||||
type: bool
|
||||
sample: True
|
||||
compatibility:
|
||||
description: The compatibility level of the task
|
||||
returned: ''
|
||||
type: int
|
||||
sample: 2
|
||||
delete_expired_task_after:
|
||||
description: The amount of time the Task Scheduler will wait before
|
||||
deleting the task after it expires.
|
||||
returned: ''
|
||||
type: str
|
||||
sample: PT10M
|
||||
disallow_start_if_on_batteries:
|
||||
description: Whether the task will not be started if the computer is
|
||||
running on battery power.
|
||||
returned: ''
|
||||
type: bool
|
||||
sample: False
|
||||
disallow_start_on_remote_app_session:
|
||||
description: Whether the task will not be started when in a remote app
|
||||
session.
|
||||
returned: ''
|
||||
type: bool
|
||||
sample: True
|
||||
enabled:
|
||||
description: Whether the task is enabled.
|
||||
returned: ''
|
||||
type: bool
|
||||
sample: True
|
||||
execution_time_limit:
|
||||
description: The amount of time allowed to complete the task.
|
||||
returned: ''
|
||||
type: str
|
||||
sample: PT72H
|
||||
hidden:
|
||||
description: Whether the task is hidden in the UI.
|
||||
returned: ''
|
||||
type: bool
|
||||
sample: False
|
||||
idle_settings:
|
||||
description: The idle settings of the task.
|
||||
returned: ''
|
||||
type: dictionary
|
||||
sample: {
|
||||
"idle_settings": "PT1H"
|
||||
}
|
||||
maintenance_settings:
|
||||
description: The maintenance settings of the task.
|
||||
returned: ''
|
||||
type: str
|
||||
sample: null
|
||||
mulitple_instances:
|
||||
description: Indicates the behaviour when starting a task that is already
|
||||
running.
|
||||
returned: ''
|
||||
type: int
|
||||
sample: 2
|
||||
network_settings:
|
||||
description: The network settings of the task.
|
||||
returned: ''
|
||||
type: dictionary
|
||||
sample: {
|
||||
"network_settings": null
|
||||
}
|
||||
priority:
|
||||
description: The priority level of the task.
|
||||
returned: ''
|
||||
type: int
|
||||
sample: 7
|
||||
restart_count:
|
||||
description: The number of times that the task will attempt to restart
|
||||
on failures.
|
||||
returned: ''
|
||||
type: int
|
||||
sample: 0
|
||||
restart_interval:
|
||||
description: How long the Task Scheduler will attempt to restart the
|
||||
task.
|
||||
returned: ''
|
||||
type: str
|
||||
sample: PT15M
|
||||
run_only_id_idle:
|
||||
description: Whether the task will run if the computer is in an idle
|
||||
state.
|
||||
returned: ''
|
||||
type: bool
|
||||
sample: True
|
||||
run_only_if_network_available:
|
||||
description: Whether the task will run only when a network is available.
|
||||
returned: ''
|
||||
type: bool
|
||||
sample: False
|
||||
start_when_available:
|
||||
description: Whether the task can start at any time after its scheduled
|
||||
time has passed.
|
||||
returned: ''
|
||||
type: bool
|
||||
sample: False
|
||||
stop_if_going_on_batteries:
|
||||
description: Whether the task will be stopped if the computer begins to
|
||||
run on battery power.
|
||||
returned: ''
|
||||
type: bool
|
||||
sample: True
|
||||
use_unified_scheduling_engine:
|
||||
description: Whether the task will use the unifed scheduling engine.
|
||||
returned: ''
|
||||
type: bool
|
||||
sample: False
|
||||
volatile:
|
||||
description: Whether thet ask is volatile.
|
||||
returned: ''
|
||||
type: bool
|
||||
sample: False
|
||||
wake_to_run:
|
||||
description: Whether the task will wake the computer when it is time to
|
||||
run the task.
|
||||
returned: ''
|
||||
type: bool
|
||||
sample: False
|
||||
state:
|
||||
description: Details on the state of the task
|
||||
returned: name is specified and task exists
|
||||
type: complex
|
||||
contains:
|
||||
last_run_time:
|
||||
description: The time the registered task was last run.
|
||||
returned: ''
|
||||
type: str
|
||||
sample: '2017-09-20T20:50:00'
|
||||
last_task_result:
|
||||
description: The results that were returned the last time the task was
|
||||
run.
|
||||
returned: ''
|
||||
type: int
|
||||
sample: 267009
|
||||
next_run_time:
|
||||
description: The time when the task is next scheduled to run.
|
||||
returned: ''
|
||||
type: str
|
||||
sample: '2017-09-20T22:50:00'
|
||||
number_of_missed_runs:
|
||||
description: The number of times a task has missed a scheduled run.
|
||||
returned: ''
|
||||
type: int
|
||||
sample: 1
|
||||
status:
|
||||
description: The status of the task, whether it is running, stopped, etc.
|
||||
returned: ''
|
||||
type: str
|
||||
sample: TASK_STATE_RUNNING
|
||||
task_exists:
|
||||
description: Whether the task at the folder exists.
|
||||
returned: name is specified
|
||||
type: boolean
|
||||
sample: True
|
||||
triggers:
|
||||
description: A list of triggers.
|
||||
returned: name is specified and task exists
|
||||
type: list
|
||||
sample: [
|
||||
{
|
||||
"delay": "PT15M",
|
||||
"enabled": true,
|
||||
"end_boundary": null,
|
||||
"execution_time_limit": null,
|
||||
"id": null,
|
||||
"repetition": {
|
||||
"repetition": false
|
||||
},
|
||||
"start_boundary": null,
|
||||
"type": "TASK_TRIGGER_BOOT"
|
||||
},
|
||||
{
|
||||
"days_of_month": "5,15,30",
|
||||
"enabled": true,
|
||||
"end_boundary": null,
|
||||
"execution_time_limit": null,
|
||||
"id": null,
|
||||
"months_of_year": "june,december",
|
||||
"random_delay": null,
|
||||
"repetition": {
|
||||
"repetition": false
|
||||
},
|
||||
"run_on_last_day_of_month": true,
|
||||
"start_boundary": "2017-09-20T03:44:38",
|
||||
"type": "TASK_TRIGGER_MONTHLY"
|
||||
}
|
||||
]
|
||||
'''
|
@ -0,0 +1 @@
|
||||
windows/ci/group3
|
@ -0,0 +1,3 @@
|
||||
---
|
||||
test_scheduled_task_stat_name: Test Task
|
||||
test_scheduled_task_stat_path: \test path
|
@ -0,0 +1,150 @@
|
||||
---
|
||||
- name: ensure task is deleted before test
|
||||
win_scheduled_task:
|
||||
name: '{{test_scheduled_task_stat_name}}'
|
||||
path: '{{test_scheduled_task_stat_path}}'
|
||||
state: absent
|
||||
|
||||
# folder stat tests
|
||||
- name: get stat of a folder that is missing
|
||||
win_scheduled_task_stat:
|
||||
path: '{{test_scheduled_task_stat_path}}'
|
||||
register: stat_folder_missing
|
||||
|
||||
- name: assert get stat of a folder that is missing
|
||||
assert:
|
||||
that:
|
||||
- stat_folder_missing.folder_exists == False
|
||||
|
||||
- name: get stat of existing folder
|
||||
win_scheduled_task_stat:
|
||||
path: \
|
||||
register: stat_folder_present
|
||||
|
||||
- name: assert get stat of existing folder
|
||||
assert:
|
||||
that:
|
||||
- stat_folder_present.folder_exists == True
|
||||
- stat_folder_present.folder_task_count is defined
|
||||
- stat_folder_present.folder_task_names is defined
|
||||
|
||||
- name: create scheduled task in folder
|
||||
win_scheduled_task:
|
||||
path: '{{test_scheduled_task_stat_path}}'
|
||||
name: '{{test_scheduled_task_stat_name}}'
|
||||
state: present
|
||||
logon_type: interactive_token
|
||||
username: Administrator
|
||||
author: Ansible Author
|
||||
description: Fake description
|
||||
execution_time_limit: PT23H
|
||||
disallow_start_if_on_batteries: false
|
||||
restart_count: 3
|
||||
restart_interval: PT15M
|
||||
actions:
|
||||
- path: cmd.exe
|
||||
- path: C:\temp\some.exe
|
||||
arguments: --help
|
||||
working_directory: C:\temp
|
||||
triggers:
|
||||
- type: boot
|
||||
delay: PT15M
|
||||
- type: monthly
|
||||
days_of_month: 5,15,30
|
||||
months_of_year: june,december
|
||||
run_on_last_day_of_month: true
|
||||
start_boundary: '2017-09-20T03:44:38'
|
||||
|
||||
- name: get stat of existing folder with task
|
||||
win_scheduled_task_stat:
|
||||
path: '{{test_scheduled_task_stat_path}}'
|
||||
register: stat_folder_with_task
|
||||
|
||||
- name: assert get stat of existing folder with task
|
||||
assert:
|
||||
that:
|
||||
- stat_folder_with_task.folder_exists == True
|
||||
- stat_folder_with_task.folder_task_count == 1
|
||||
- stat_folder_with_task.folder_task_names[0] == "Test Task"
|
||||
- stat_folder_with_task.task_exists is not defined
|
||||
|
||||
# task stat tests
|
||||
- name: get stat of missing task
|
||||
win_scheduled_task_stat:
|
||||
path: '{{test_scheduled_task_stat_path}}'
|
||||
name: fake task
|
||||
register: stat_task_missing
|
||||
|
||||
- name: assert get stat of missing task
|
||||
assert:
|
||||
that:
|
||||
- stat_task_missing.task_exists == False
|
||||
|
||||
- name: get stat of existing task
|
||||
win_scheduled_task_stat:
|
||||
path: '{{test_scheduled_task_stat_path}}'
|
||||
name: '{{test_scheduled_task_stat_name}}'
|
||||
register: stat_task_present
|
||||
|
||||
- name: assert get stat of existing task
|
||||
assert:
|
||||
that:
|
||||
- stat_task_present.task_exists == True
|
||||
- stat_task_present.actions|count == 2
|
||||
- stat_task_present.actions[0].path == "cmd.exe"
|
||||
- stat_task_present.actions[0].type == "TASK_ACTION_EXEC"
|
||||
- stat_task_present.actions[0].working_directory == None
|
||||
- stat_task_present.actions[1].arguments == "--help"
|
||||
- stat_task_present.actions[1].path == "C:\\temp\some.exe"
|
||||
- stat_task_present.actions[1].type == "TASK_ACTION_EXEC"
|
||||
- stat_task_present.actions[1].working_directory == "C:\\temp"
|
||||
- stat_task_present.principal.display_name == None
|
||||
- stat_task_present.principal.group_id == None
|
||||
- stat_task_present.principal.logon_type == "TASK_LOGON_INTERACTIVE_TOKEN"
|
||||
- stat_task_present.principal.run_level == "TASK_RUNLEVEL_LUA"
|
||||
- stat_task_present.principal.user_id.endswith("Administrator")
|
||||
- stat_task_present.registration_info.author == "Ansible Author"
|
||||
- stat_task_present.registration_info.date is defined
|
||||
- stat_task_present.registration_info.description == "Fake description"
|
||||
- stat_task_present.settings.disallow_start_if_on_batteries == False
|
||||
- stat_task_present.settings.execution_time_limit == "PT23H"
|
||||
- stat_task_present.settings.restart_count == 3
|
||||
- stat_task_present.settings.restart_interval == "PT15M"
|
||||
- stat_task_present.state.status == "TASK_STATE_READY"
|
||||
- stat_task_present.triggers|count == 2
|
||||
- stat_task_present.triggers[0].delay == "PT15M"
|
||||
- stat_task_present.triggers[0].type == "TASK_TRIGGER_BOOT"
|
||||
- stat_task_present.triggers[1].days_of_month == "5,15,30"
|
||||
- stat_task_present.triggers[1].months_of_year == "june,december"
|
||||
- stat_task_present.triggers[1].run_on_last_day_of_month == True
|
||||
- stat_task_present.triggers[1].start_boundary == "2017-09-20T03:44:38"
|
||||
- stat_task_present.triggers[1].type == "TASK_TRIGGER_MONTHLY"
|
||||
|
||||
- name: change principal to system account so it will run in the next step
|
||||
win_scheduled_task:
|
||||
name: '{{test_scheduled_task_stat_name}}'
|
||||
path: '{{test_scheduled_task_stat_path}}'
|
||||
username: SYSTEM
|
||||
|
||||
- name: start the scheduled task
|
||||
win_command: schtasks.exe /Run /TN "{{test_scheduled_task_stat_path}}\{{test_scheduled_task_stat_name}}"
|
||||
|
||||
- name: get stat of running task
|
||||
win_scheduled_task_stat:
|
||||
path: '{{test_scheduled_task_stat_path}}'
|
||||
name: '{{test_scheduled_task_stat_name}}'
|
||||
register: stat_task_running
|
||||
|
||||
- name: assert stat of running task
|
||||
assert:
|
||||
that:
|
||||
- stat_task_running.state.status == "TASK_STATE_RUNNING"
|
||||
|
||||
- name: stop the scheduled task
|
||||
win_command: schtasks.exe /End /TN "{{test_scheduled_task_stat_path}}\{{test_scheduled_task_stat_name}}"
|
||||
|
||||
- name: ensure task is delete after test
|
||||
win_scheduled_task:
|
||||
name: '{{test_scheduled_task_stat_name}}'
|
||||
path: '{{test_scheduled_task_stat_path}}'
|
||||
state: absent
|
Loading…
Reference in New Issue