# Copyright (c) IBM Corporation 2023


DOCUMENTATION = r"""
role: zmf_zmsc_run_management_service
short_description: Role runs a z/OS management service
description:
    - >
      The B(IBM z/OSMF collection) provides an Ansible role, referred to as
      B(zmf_zmsc_run_management_service), to run a z/OS management service
      published in B(z/OS Management Services Catalog).
    - >
      Management Service referenced by playbook must be published in
      I(z/OS Management Services Catalog).
    - >
      This role will generate a unique JSON file that holds service
      instance information. The file location is in following format,
      C(<instance_record_dir>/<catalog_service_name>-<instance objectId>.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 run management service role uses to capture
              various information (in JSON format) about the service
              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
    catalog_service_name:
        description:
            - Service name of the management service to be run.
        required: True
        type: str
    category_name:
        description:
            - Category name associated with the management service to be run. If there after
              are multiple managment services with same name, this parameter is required to
              uniquely identify management service to be run.
        required: False
        type: str
    change_record_number:
        description:
            - >
              Change record number associated with the change being performed by
              management service. This information is required when z/OS Management
              Service Catalog is configured to require change record number to run
              any management service.
        required: False
        type: str
        default: null
    job_statement:
        description:
            - >
              Job statement to be used when running a management service.
        required: False
        type: str
        default: null
    system_nickname:
        description:
            - System nickname as specified in the z/OSMF Systems table.
            - >
              If this variable is not specified, management service will run 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 management service to be
              run.
            - >
              This variable is required if management service expects specific
              inputs from user.
              This is a json variable and needs to be in following
              format, C({ "var1":"value1","var2":"value2",...})
        required: False
        type: json
        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/xxx.json").
      This message includes a file path and file name where instance specific
      information is returned.

"""

EXAMPLES = r"""
- name: Run z/OS Management Service
  hosts: sampleHost
  gather_facts: no
  collections: 
    - ibm.ibm_zosmf
  tasks: 
    - include_role:
        name: zmf_zmsc_run_management_service
      vars:
        catalog_service_namme: "<fill-me-service-name>"
        category_name: "<optional-category-name>"
        change_record_number: "<optional-change_record_number>"
        job_statement: "<optional-job_statement>"
        systems_name: "<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
"""