# Copyright (c) IBM Corporation 2021


DOCUMENTATION = r"""
role: zmf_cpm_list_software_templates
short_description: Role lists all published z/OS software templates
description:
    - >
      The B(IBM z/OSMF collection) provides an Ansible role, referred to as
      B(zmf_cpm_list_software_templates), to obtain list of all the published
      templates that can be used to provision z/OS middleware such as 
      IBM Customer Information Control System (CICS®), IBM Db2®, IBM MQ, and
      IBM WebSphere Application Server or any other software service from
      B(IBM Cloud Provisioning and Management (CP&M)) catalog.
author:
    - Hiren Shah (@shreeji818)
options:
    zmf_host:
        description:
            - >
              Hostname of the z/OSMF server, specified in the inventory file
              or vars file.
        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
              value for this parameter in the inventory file or vars file.
        required: False
        type: str
        default: 443
    zmf_user:
        description:
            - User name to be used for authenticating with the z/OSMF server.
            - >
              This variable can be specified in the inventory file or vars
              file, or prompted when playbook is run.
        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 vars
              file, or prompted when playbook is run.
        required: True
        type: str
    instance_record_dir:
        description:
            - >
              Directory path that the provisioning role uses to capture
              list of published templates (in JSON format).
            - >
              On many system default value C("/tmp") used for this variable
              may not be acceptable because C("/tmp") directory can be
              transient on the system.
              In such cases it is recommended to specify non-default value for
              this variable.
              This variable can be specified in the inventory file or vars
              file.
        required: False
        type: str
        default: /tmp
notes:
    - >
      The given example assumes that you have an inventory file
      I(inventory.yml) and host vars I(sampleHost.yml) with appropriate values
      to identify the target z/OSMF server end point.
    - >
      When playbooks completes, a message shown in following example is
      displayed, C("msg": "Published Template List saved at: /tmp/xxx.json").
      This message includes a file path and file name where the list of published template
      is returned.
    
"""

EXAMPLES = r"""
- name: list published provisioning templates
  hosts: sampleHost
  gather_facts: no
  collections: 
    - ibm.ibm_zosmf
  tasks: 
    - include_role:
        name: zmf_cpm_list_software_templates
      
"""

# 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
"""