win_description Module (#61629)

* win_description Module

Module to change Windows description and Windows license owner information.

* LiteralPath updated

changed -path to -LiteralPath in the script

* Version and metadata_version

version_added updated to 2.10
Metadata_version set to 1.1

* version updated

version_added changed to '2.10'

* Changes based on feedback

* removed some redundant checks

* Rename win_description.ps1 to win_computer_description.ps1

* Rename win_description.py to win_computer_description.py

* Module name change

* Integration tests added

* added aliases file

* Change compatibility from 2008 to 2008R2

* Update aliases

lib/ansible/modules/windows/win_computer_description.ps1

@@ -0,0 +1,54 @@
+#!powershell
+
+# Copyright: (c) 2019, RusoSova
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+#AnsibleRequires -CSharpUtil Ansible.Basic
+#AnsibleRequires -OSVersion 6.1
+
+$spec = @{
+    options = @{
+        owner = @{ type="str" }
+        organization = @{ type="str" }
+        description = @{ type="str" }
+    }
+    required_one_of = @(
+        ,@('owner', 'organization', 'description')
+    )
+    supports_check_mode = $true
+}
+
+$module = [Ansible.Basic.AnsibleModule]::Create($args, $spec)
+
+$owner = $module.Params.owner
+$organization = $module.Params.organization
+$description = $module.Params.description
+$regPath="HKLM:\SOFTWARE\Microsoft\Windows NT\CurrentVersion\"
+
+#Change description
+if ($description -or $description -eq "") {
+    $descriptionObject=Get-CimInstance -class "Win32_OperatingSystem"
+    if ($description -cne $descriptionObject.description) {
+        Set-CimInstance -InputObject $descriptionObject -Property @{"Description"="$description"} -WhatIf:$module.CheckMode
+        $module.Result.changed = $true
+    }
+}
+
+#Change owner
+if ($owner -or $owner -eq "") {
+    $curentOwner=(Get-ItemProperty -LiteralPath $regPath -Name RegisteredOwner).RegisteredOwner
+    if ($curentOwner -cne $owner) {
+        Set-ItemProperty -LiteralPath $regPath -Name "RegisteredOwner" -Value $owner -WhatIf:$module.CheckMode
+        $module.Result.changed = $true
+    }
+}
+
+#Change organization
+if ($organization -or $organization -eq "") {
+    $curentOrganization=(Get-ItemProperty -LiteralPath $regPath -Name RegisteredOrganization).RegisteredOrganization
+    if ($curentOrganization -cne $organization) {
+        Set-ItemProperty -LiteralPath $regPath -Name "RegisteredOrganization" -Value $organization -WhatIf:$module.CheckMode
+        $module.Result.changed = $true
+    }
+}
+$module.ExitJson()

lib/ansible/modules/windows/win_computer_description.py

@@ -0,0 +1,75 @@
+#!/usr/bin/python
+# -*- coding: utf-8 -*-
+
+# Copyright: (c) 2019, RusoSova
+# 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
+
+from __future__ import absolute_import, division, print_function
+__metaclass__ = type
+
+ANSIBLE_METADATA = {
+    'metadata_version': '1.1',
+    'status': ['preview'],
+    'supported_by': 'community'
+}
+
+DOCUMENTATION = r'''
+---
+module: win_computer_description
+short_description: Set windows description, owner and organization
+description:
+ - This module sets Windows description that is shown under My Computer properties. Module also sets
+   Windows license owner and organization. License information can be viewed by running winver commad.
+options:
+ description:
+   description:
+     - String value to apply to Windows descripton. Specify value of "" to clear the value.
+   required: false
+   type: str
+ organization:
+   description:
+     - String value of organization that the Windows is licensed to. Specify value of "" to clear the value.
+   required: false
+   type: str
+ owner:
+   description:
+     - String value of the persona that the Windows is licensed to. Specify value of "" to clear the value.
+   required: false
+   type: str
+version_added: '2.10'
+author:
+ - RusoSova (@RusoSova)
+'''
+
+EXAMPLES = r'''
+- name: Set Windows description, owner and organization
+  win_computer_description:
+   description: Best Box
+   owner: RusoSova
+   organization: MyOrg
+  register: result
+
+- name: Set Windows description only
+  win_computer_description:
+   description: This is my Windows machine
+  register: result
+
+- name: Set organization and clear owner field
+  win_computer_description:
+   owner: ''
+   organization: Black Mesa
+
+- name: Clear organization, description and owner
+  win_computer_description:
+   organization: ""
+   owner: ""
+   description: ""
+  register: result
+'''
+
+RETURN = r'''
+#
+'''

test/integration/targets/win_computer_description/aliases

@@ -0,0 +1,2 @@
+shippable/windows/group3
+skip/windows/2008

test/integration/targets/win_computer_description/defaults/main.yml

@@ -0,0 +1,6 @@
+test_description: This is my computer
+test_organization: iddqd
+test_owner: BFG
+test_description2: This is not my computer
+test_organization2: idkfa
+test_owner2: CACODEMON

test/integration/targets/win_computer_description/tasks/main.yml

@@ -0,0 +1,200 @@
+---
+- name: Blank out description, organization and owner
+  win_computer_description:
+   description: ""
+   organization: ""
+   owner: ""
+  register: blank_set
+  check_mode: no
+
+- name: Change description, organization and owner in check mode
+  win_computer_description:
+   description: "{{ test_description }}"
+   organization: "{{ test_organization }}"
+   owner: "{{ test_owner }}"
+  register: change1_checkmode
+  check_mode: yes
+
+- name: Change description, organization and owner
+  win_computer_description:
+   description: "{{ test_description }}"
+   organization: "{{ test_organization }}"
+   owner: "{{ test_owner }}"
+  register: change1_set
+  check_mode: no
+
+- name: Change description, organization and owner 2nd time, there should be no change happening
+  win_computer_description:
+   description: "{{ test_description }}"
+   organization: "{{ test_organization }}"
+   owner: "{{ test_owner }}"
+  register: change1_set2
+  check_mode: no
+
+- name: Assert that the above tasks returned the expected results
+  assert:
+   that:
+   - change1_checkmode is changed
+   - change1_set is changed
+   - change1_set2 is not changed
+
+- name: Get machine description
+  win_shell: (Get-CimInstance -class "Win32_OperatingSystem").description
+  register: description1_changed
+
+- name: Get organization name
+  win_reg_stat:
+   path: HKLM:\SOFTWARE\Microsoft\Windows NT\CurrentVersion
+   name: RegisteredOrganization
+  register: organization1_changed
+
+- name: Get owner
+  win_reg_stat:
+   path: HKLM:\SOFTWARE\Microsoft\Windows NT\CurrentVersion
+   name: RegisteredOwner
+  register: owner1_changed
+
+- name: Assert that retrieved values are equal to the values provided in the variables
+  assert:
+   that:
+   - description1_changed.stdout == "{{ test_description }}\r\n"
+   - organization1_changed.value == "{{ test_organization }}"
+   - owner1_changed.value == "{{ test_owner }}"
+
+- name: Change description and owner only in check mode
+  win_computer_description:
+   description: "{{ test_description2 }}"
+   owner: "{{ test_owner2 }}"
+  register: change2_checkmode
+  check_mode: yes
+
+- name: Change description and owner only
+  win_computer_description:
+   description: "{{ test_description2 }}"
+   owner: "{{ test_owner2 }}"
+  register: change2_set
+  check_mode: no
+
+- name: Change description and owner only 2nd time, there should be no change happening
+  win_computer_description:
+   description: "{{ test_description2 }}"
+   owner: "{{ test_owner2 }}"
+  register: change2_set2
+  check_mode: no
+
+- name: Assert that the above tasks returned the expected results
+  assert:
+   that:
+   - change2_checkmode is changed
+   - change2_set is changed
+   - change2_set2 is not changed
+
+- name: Get machine description
+  win_shell: (Get-CimInstance -class "Win32_OperatingSystem").description
+  register: description2_changed
+
+- name: Get organization name
+  win_reg_stat:
+   path: HKLM:\SOFTWARE\Microsoft\Windows NT\CurrentVersion
+   name: RegisteredOrganization
+  register: organization2_changed
+
+- name: Get owner
+  win_reg_stat:
+   path: HKLM:\SOFTWARE\Microsoft\Windows NT\CurrentVersion
+   name: RegisteredOwner
+  register: owner2_changed
+
+- name: Assert that retrieved values are equal to the desired values
+  assert:
+   that:
+   - description2_changed.stdout == "{{ test_description2 }}\r\n"
+   - organization2_changed.value == "{{ test_organization }}"
+   - owner2_changed.value == "{{ test_owner2 }}"
+
+- name: Change organization only in check mode
+  win_computer_description:
+   organization: "{{ test_organization2 }}"
+  register: change3_checkmode
+  check_mode: yes
+
+- name: Change organization only in check mode
+  win_computer_description:
+   organization: "{{ test_organization2 }}"
+  register: change3_set
+  check_mode: no
+
+- name: Change organization only in check mode
+  win_computer_description:
+   organization: "{{ test_organization2 }}"
+  register: change3_set2
+  check_mode: no
+
+- name: Assert that the above tasks returned the expected results
+  assert:
+   that:
+   - change3_checkmode is changed
+   - change3_set is changed
+   - change3_set2 is not changed
+
+- name: Get machine description
+  win_shell: (Get-CimInstance -class "Win32_OperatingSystem").description
+  register: description3_changed
+
+- name: Get organization name
+  win_reg_stat:
+   path: HKLM:\SOFTWARE\Microsoft\Windows NT\CurrentVersion
+   name: RegisteredOrganization
+  register: organization3_changed
+
+- name: Get owner
+  win_reg_stat:
+   path: HKLM:\SOFTWARE\Microsoft\Windows NT\CurrentVersion
+   name: RegisteredOwner
+  register: owner3_changed
+
+- name: Assert that retrieved values are equal to the desired values
+  assert:
+   that:
+   - description3_changed.stdout == "{{ test_description2 }}\r\n"
+   - organization3_changed.value == "{{ test_organization2 }}"
+   - owner3_changed.value == "{{ test_owner2 }}"
+
+- name: Try to apply the same values again in check mode, there should be no change
+  win_computer_description:
+   description: "{{ test_description2 }}"
+   organization: "{{ test_organization2 }}"
+   owner: "{{ test_owner2 }}"
+  register: change4_checkmode
+  check_mode: yes
+
+- name: Try to apply the same values again, there should be no change
+  win_computer_description:
+   description: "{{ test_description2 }}"
+   organization: "{{ test_organization2 }}"
+   owner: "{{ test_owner2 }}"
+  register: change4_set
+  check_mode: no
+
+- name: Try to apply the same values again for 2nd time, there should be no change
+  win_computer_description:
+   description: "{{ test_description2 }}"
+   organization: "{{ test_organization2 }}"
+   owner: "{{ test_owner2 }}"
+  register: change4_set2
+  check_mode: no
+
+- name: Assert that the above tasks returned the expected results
+  assert:
+   that:
+   - change4_checkmode is not changed
+   - change4_set is not changed
+   - change4_set2 is not changed
+
+- name: Blank the test values
+  win_computer_description:
+   description: ''
+   organization: ''
+   owner: ''
+  register: blank2_set
+  check_mode: no