# Copyright (c) IBM Corporation 2021


DOCUMENTATION = r"""
role: zmf_cpm_provision_software_service
short_description: Role provisions a z/OS software service
description:
    - >
      The B(IBM z/OSMF collection) provides an Ansible role, referred to as
      B(zmf_cpm_provision_software_service), to provision a z/OS middleware
      such as IBM Customer Information Control System (CICS®), IBM Db2®, IBM
      Information Management System (IMS™), IBM MQ, and IBM WebSphere
      Application Server or any other software service by using an
      B(IBM Cloud Provisioning and Management (CP&M)) template.
    - >
      Template referenced by playbook must be published in
      I(z/OSMF Software Services Catalog).
    - >
      This role will generate a unique JSON file that holds provisioned
      instance information. The file location is in following format,
      C(<instance_record_dir>/<cpm_template_name>-<instance external_name>.json)
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
              various information (in JSON format) about the provisioned
              instance.
            - >
              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
    cpm_template_name:
        description:
            - Template name for the software service to be provisioned.
        required: True
        type: str
    domain_name:
        description:
            - Cloud domain name that is associated with the template.
        required: True
        type: str
    tenant_name:
        description:
            - >
              CP&M Tenant name that is associated with the user who is performing
              this role.
            - >
              This variable is required if I(zmf_user) is associated with
              multiple CP&M tenants.
        required: False
        type: str
        default: null
    systems_nicknames:
        description:
            - System nickname as specified in the z/OSMF Systems table.
            - >
              If this variable is not specified, provisioning is performed on
              the system where z/OSMF is currently running.
        required: False
        type: str
        default: null
    input_vars:
        description:
            - >
              Input variable names and values for the software service to be
              provisioned.
            - >
              This variable is required if software service expects specific
              inputs from user.
              This is a dictionary variable and needs to be in following
              format, C([{ "name":"VAR1","value":"VAR1_VALUE"},{..},...])
        required: False
        type: dict
        default: null
    zmf_body:
        description:
            - >
              Instead of specifying I(domain_name), I(tenant_name),
              I(system_nicknames) and I(input_variable) individually, this
              parameter can be used to pass them as a dictionary variable.
              This variable needs to be in following format,
            - C({)
            - C("domain-name":"{{ domain_name }}",)
            - C("domain-name":"{{ domain_name }}",)
            - C("systems-nicknames":["{{ systems_nicknames }}"],)
            - C("input-variables":"{{ input_vars }}")
            - C(})
        required: False
        type: dict
        default: null
    api_polling_retry_count:
        description:
            - >
              Total retry attempts allowed before the role exits with failure,
              waiting on the instance action to complete.
            - >
              This variable can be specified in the inventory file or vars
              file.
        required: False
        type: int
        default: 50
    api_polling_interval_seconds:
        description:
            - >
              Interval time (in seconds) for each polling request.
            - >
              This variable can be specified in the inventory file or vars
              file.
        required: False
        type: int
        default: 10
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": "Instance record saved at: /tmp/xxx.json").
      This message includes a file path and file name where instance specific
      information is returned.
      This file is required for M(zmf_cpm_manage_software_instance) and
      M(zmf_cpm_remove_software_instance) roles.
"""

EXAMPLES = r"""
- name: Provision a z/OS Middleware service
  hosts: sampleHost
  gather_facts: no
  collections: 
    - ibm.ibm_zosmf
  tasks: 
    - include_role:
        name: zmf_cpm_provision_software_service
      vars:
        cpm_template_name: "<fill-me-template-name>"
        domain_name: "<domain-name>"
        tenant_name: "<optional-tenant-name>"
        systems_nicknames: "<optional-system-name>"
        input_vars: "<optional-input-vars>"
        
"""

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