VMware: Update vmware_guest_powerstate (#57000)

* Updated documentation
* Updated testcases
* Updated example
* Updated logic
* Provided option to specify task name, task description, task enable status etc.

Fixes: #56987

Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com>

lib/ansible/modules/cloud/vmware/vmware_guest_powerstate.py

@@ -50,7 +50,7 @@ options:
     version_added: '2.8'
   folder:
     description:
-    - Destination folder, absolute or relative path to find an existing guest or create the new guest.
+    - Destination folder, absolute or relative path to find an existing guest.
     - The folder should include the datacenter. ESX's datacenter is ha-datacenter
     - 'Examples:'
     - '   folder: /ha-datacenter/vm'
@@ -62,14 +62,32 @@ options:
     - '   folder: /folder1/datacenter1/vm'
     - '   folder: folder1/datacenter1/vm'
     - '   folder: /folder1/datacenter1/vm/folder2'
-    - '   folder: vm/folder2'
-    - '   folder: folder2'
-    default: /vm
   scheduled_at:
     description:
     - Date and time in string format at which specificed task needs to be performed.
     - "The required format for date and time - 'dd/mm/yyyy hh:mm'."
     - Scheduling task requires vCenter server. A standalone ESXi server does not support this option.
+  schedule_task_name:
+    description:
+    - Name of schedule task.
+    - Valid only if C(scheduled_at) is specified.
+    type: str
+    required: False
+    version_added: '2.9'
+  schedule_task_description:
+    description:
+    - Description of schedule task.
+    - Valid only if C(scheduled_at) is specified.
+    type: str
+    required: False
+    version_added: '2.9'
+  schedule_task_enabled:
+    description:
+    - Flag to indicate whether the scheduled task is enabled or disabled.
+    type: bool
+    required: False
+    default: True
+    version_added: '2.9'
   force:
     description:
     - Ignore warnings and complete the actions.
@@ -109,6 +127,9 @@ EXAMPLES = r'''
     name: "{{ guest_name }}"
     state: powered-off
     scheduled_at: "09/01/2018 10:18"
+    schedule_task_name: "task_00001"
+    schedule_task_description: "Sample task to poweroff VM"
+    schedule_task_enabled: True
   delegate_to: localhost
   register: deploy_at_schedule_datetime
 
@@ -131,6 +152,7 @@ try:
 except ImportError:
     pass
 
+from random import randint
 from datetime import datetime
 from ansible.module_utils.basic import AnsibleModule
 from ansible.module_utils.vmware import PyVmomi, set_vm_power_state, vmware_argument_spec
@@ -146,9 +168,12 @@ def main():
         name_match=dict(type='str', choices=['first', 'last'], default='first'),
         uuid=dict(type='str'),
         use_instance_uuid=dict(type='bool', default=False),
-        folder=dict(type='str', default='/vm'),
+        folder=dict(type='str'),
         force=dict(type='bool', default=False),
         scheduled_at=dict(type='str'),
+        schedule_task_name=dict(),
+        schedule_task_description=dict(),
+        schedule_task_enabled=dict(type='bool', default=True),
         state_change_timeout=dict(type='int', default=0),
     )
 
@@ -174,6 +199,7 @@ def main():
                 module.fail_json(msg="Scheduling task requires vCenter, hostname %s "
                                      "is an ESXi server." % module.params.get('hostname'))
             powerstate = {
+                'present': vim.VirtualMachine.PowerOn,
                 'powered-off': vim.VirtualMachine.PowerOff,
                 'powered-on': vim.VirtualMachine.PowerOn,
                 'reboot-guest': vim.VirtualMachine.RebootGuest,
@@ -188,16 +214,18 @@ def main():
                 module.fail_json(msg="Failed to convert given date and time string to Python datetime object,"
                                      "please specify string in 'dd/mm/yyyy hh:mm' format: %s" % to_native(e))
             schedule_task_spec = vim.scheduler.ScheduledTaskSpec()
-            schedule_task_desc = 'Schedule task for vm %s for operation %s at %s' % (vm.name,
-                                                                                     module.params.get('state'),
-                                                                                     scheduled_at)
-            schedule_task_spec.name = schedule_task_desc
+            schedule_task_name = module.params['schedule_task_name'] or 'task_%s' % str(randint(10000, 99999))
+            schedule_task_desc = module.params['schedule_task_description']
+            if schedule_task_desc is None:
+                schedule_task_desc = 'Schedule task for vm %s for ' \
+                                     'operation %s at %s' % (vm.name, module.params['state'], scheduled_at)
+            schedule_task_spec.name = schedule_task_name
             schedule_task_spec.description = schedule_task_desc
             schedule_task_spec.scheduler = vim.scheduler.OnceTaskScheduler()
             schedule_task_spec.scheduler.runAt = dt
             schedule_task_spec.action = vim.action.MethodAction()
-            schedule_task_spec.action.name = powerstate[module.params.get('state')]
-            schedule_task_spec.enabled = True
+            schedule_task_spec.action.name = powerstate[module.params['state']]
+            schedule_task_spec.enabled = module.params['schedule_task_enabled']
 
             try:
                 pyv.content.scheduledTaskManager.CreateScheduledTask(vm, schedule_task_spec)