# Copyright (c) IBM Corporation 2021


DOCUMENTATION = r"""
role: zmf_cpm_create_software_instance
short_description: Role creates a z/OS software instance
description:
    - >
      The B(IBM z/OSMF collection) provides an Ansible role, referred to as
      B(zmf_cpm_create_software_instance), to create an instance of manually
      configured z/OS software 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 z/OS Software in
      B(IBM Cloud Provisioning and Management (CP&M)) registry.
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
    systems_name:
        description:
            - The name of the system where the software is currently manullay
              configured
        required: True
        type: str
    sysplex_name:
        description:
            - The name of the sysplex where the software is currently manullay
              configured
        required: True
        type: str
    external_name:
        description:
            - The external name associated with the manually configured
              software
        required: True
        type: str
    vendor_name:
        description:
            - The vendor who proivded the software
        required: True
        type: str
    software_type:
        description:
            - The software type of the configured software
        required: True
        type: str
    product_version:
        description:
            - The software product version of the configured software 
        required: True
        type: str
    instance_description:
        description:
            - Description for the configured software
        required: True
        type: str
    instance_provider:
        description:
            - User who provided the software instance information
        required: True
        type: str
    instance_owner:
        description:
            - Owner of the software instance. Software instance can be removed
              only by this user
        required: True
        type: str
    instance_var_json_path:
        description:
            - Directory path for the JSON file that holds variables associated with
              software instance. Specify the file name that includes variables
              associated with the configured softare instance e.g. /tmp/myVar.json. 
              File contains json array of variables with name, value and visibility
              format where name identifies variable name, value identifies variable
              value and visibility identifies whether variable is "public" or "private".
              For example,
            - C([)
            - C({)
            - C("name":"VAR1",)
            - C("value":"VAR1_VALUE",)
            - C("visibility":"public")
            - C(},)
            - C({)
            - C("name":"VAR2",)
            - C("value":"VAR2_VALUE",)
            - C("visibility":"public")
            - C(},)
            - C(....]) 
        required: False
        type: dict
        default: null
    zmf_body:
        description:
            - Instead of specifying I(system-name), I(sysplex-name), I(external_name), I(vendor_name),
              I(product_version), I(instance_description), I(instance_owner), I(instance_provider), and 
              I(instance_var_json_path) individually, this parameter can be used to pass them as a
              dictionary variable. This variable needs to be in following format,
              
            - C({)
            - C("system-name":"{{ system_name }}",)
            - C("sysplex-name":"{{ sysplex_name }}",)
            - C("registry-type":"general",)
            - C("external-name":"{{ external_name }}",)
            - C("type":"{{ software_type }}",)
            - C("vendor":"{{ vendor_name }}",)
            - C("version":"{{ product_version }}",)
            - C("description":"{{ instance_description }}",)
            - C("owner":"{{ instance_owner }}",)
            - C("provider":"{{ instance_provider }}",)
            - C("state":"provisioned",)
            - C("actions":[ {"name":"deprovision","type":"instructions",
                "instructions":"perform this action to deprovision"} ],)
            - C("variables":{{ instance_variable_record }})
            - C(})
            - >
              Note I(instance_variable_record) is a dictionary object and needs to be in following format

            - C([)
            - C({)
            - C("name":"VAR1",)
            - C("value":"VAR1_VALUE",)
            - C("visibility":"public")
            - C(},)
            - C({)
            - C("name":"VAR2",)
            - C("value":"VAR2_VALUE",)
            - C("visibility":"public")
            - C(},)
            - C(....])
        required: False
        type: dict
        default: null
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/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: create instance of z/OS software in software instance registry
  hosts: sampleHost
  gather_facts: no
  collections: 
    - ibm.ibm_zosmf
  tasks: 
    - include_role:
        name: zmf_cpm_create_software_instance
      vars:
        system_name: "<fill-me>"
        sysplex_name: "<fill-me>" 
        external_name: "<fill-me>"
        software_type: "<fill-me>"
        vendor_name: "<fill-me>"
        product_version: "<fill-me>"
        instance_description: "<fill-me>"
        instance_owner: "<fill-me>"
        instance_provider: "<fill-me>"
        instance_var_json_path: "<fill-me-file-path-and-name>" 
"""

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