# Copyright (c) IBM Corporation 2024


DOCUMENTATION = r"""
role: zmf_swmgmt_zos_system_uuid
short_description: Retrieve the z/OS system UUID
description:
    - >
      The B(IBM z/OSMF collection) provides an Ansible role, referred to as
      B(zmf_swmgmt_zos_system_uuid), to retrieve the z/OS system UUID for the
      specified system nickname. The UUID identifies the software instance
      object that corresponds to the installed software for the specified
      z/OSMF host system.  The UUID can be used to uniquely identify a
      software instance object to be acted upon by other Ansible roles.
author:
    - Taylor Digilio (Taylor.Digilio@ibm.com)
options:
    zmf_host:
        description:
            - >
              Hostname of the z/OSMF server, specified in the inventory file
              or as an argument on the playbook command.
        required: True
        type: str
    zmf_port:
        description:
            - >
              Port number of the z/OSMF server.
              If z/OSMF is not using the default port, you need to specify a
              value for this parameter in the inventory file or as an argument on
              the playbook command.
        required: False
        type: str
        default: 443
    zmf_user:
        description:
            - User ID for authenticating with the z/OSMF server.
            - >
              This variable can be specified in the inventory file or as an argument on
              the playbook command.
        required: True
        type: str
    zmf_password:
        description:
            - Password to be used for authenticating with z/OSMF server.
            - >
              This variable can be specified in the inventory file or as an argument on
              the playbook command.
        required: True
        type: str
    system_nickname:
        description:
            - >
              Nickname of the z/OSMF host system.
            - >
              This variable can be specified in the inventory file or as an argument on
              the playbook command.
        required: True
        type: str
    remote_zmf_user:
        description:
            - >
              User ID for authenticating with a remote z/OSMF server.  Used only to retrieve the UUID of
              a remote z/OSMF server.
        required: False
        type: str
    remote_zmf_password:
        description:
            - Password for authenticating with a remote z/OSMF server.
        required: False
        type: str
    proxy_zmf_user:
        description:
            - User ID for authenticating with an HTTP proxy server.
        required: False
        type: str
    proxy_zmf_password:
        description:
            - Password for authenticating with an HTTP proxy server.
        required: False
        type: str
notes:
    - >
      The given example assumes you have an inventory file
      I(inventory.yml) that contains the values for the variables described above,
      such as z/OSMF host server, userid, password, system, and response file name.
    - >
      Command syntax to call a playbook using an inventory file:
      C(ansible-playbook -i inventory software_management_system_uuid_CICDtest1.yml)
    - >
      Command syntax to call a playbook using command arguments:
      C(ansible-playbook software_management_system_uuid_CICDtest1.yml -e zmf_user=zosmf**
      -e zmf_password=zosmf**)
    - >
      When the role is executed, a message shown in following example is
      displayed, C("msg": "Output filename= /tmp/xxx/zos_system_uuid_response.json").
      This message includes a file path and file name where the z/OS system UUID
      is saved.
    - >
      Refer to https://www.ibm.com/docs/en/zos/3.1.0?topic=services-retrieve-zos-system-uuid
      for more information on the REST API's request and response JSON.

"""

EXAMPLES = r"""
- name: sample of retrieving the z/OS system UUID
  hosts: sampleHost
  gather_facts: no
  collections:
    - ibm.ibm_zosmf

  tasks:
    - include_role :
        name: zmf_swmgmt_zos_system_uuid

"""

# Roles don't return anything.
# But RETURN block must be defined for doc extraction tooling to avoid error.
# The content in RETURN block will not be display in doc-site.
RETURN = r"""
changed:
    description: Indicates if any change is made during the role operation.
    returned: always
    type: bool
"""