# Copyright (c) IBM Corporation 2021


DOCUMENTATION = r"""
role: zmf_workflow_complete
short_description: Role completes a z/OS workflow
description:
    - Complete a z/OS workflow, either forcibly or idempotently.
    - >
      This role runs z/OSMF workflows that are located on the target z/OS
      managed node.
      The workflows must be z/OSMF XML workflows and be located in a z/OS UNIX
      System Services (z/OS UNIX) filesystem.
author:
    - Yang Cao (@zosmf-Young)
    - Yun Juan Yang (@zosmf-Robyn)
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, specified in the inventory
              file or vars file.
        required: False
        type: int
        default: null
    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 when I(zmf_crt) and I(zmf_key) are not supplied.
            - >
              If I(zmf_crt) and I(zmf_key) are supplied, I(zmf_user) and
              I(zmf_password) are ignored.
        required: False
        type: str
        default: null
    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 when I(zmf_crt) and I(zmf_key) are not supplied.
            - >
              If I(zmf_crt) and I(zmf_key) are supplied, I(zmf_user) and
              I(zmf_password) are ignored.
        required: False
        type: str
        default: null
    zmf_crt:
        description:
            - >
              Location of the PEM-formatted certificate chain file
              to be used for HTTPS client authentication.
            - >
              This variable can be specified in the inventory file or vars
              file, or prompted when playbook is run.
            - Required when I(zmf_user) and I(zmf_password) are not supplied.
        required: False
        type: str
        default: null
    zmf_key:
        description:
            - >
              Location of the PEM-formatted file with your private key
              to be used for HTTPS client authentication.
            - >
              This variable can be specified in the inventory file or vars
              file, or prompted when playbook is run.
            - Required when I(zmf_user) and I(zmf_password) are not supplied.
        required: False
        type: str
        default: null
    workflow_name:
        description:
            - Descriptive name of the workflow.
            - >
              The workflow name is not case-sensitive, for example,
              C(MyWorkflow) and C(MYWORKFLOW) are the same workflow.
        required: True
        type: str
    workflow_file:
        description:
            - Location of the workflow definition file.
        required: False
        type: str
        default: null
    workflow_owner:
        description:
            - User name of the workflow owner.
            - If this value is omitted, I(zmf_user) is used as workflow owner.
        required: False
        type: str
        default: null
    workflow_file_system:
        description:
            - >
              Nickname of the system on which the specified workflow
              definition file resides, along with any related files.
        required: False
        type: str
        default: null
    workflow_vars_file:
        description:
            - >
              Location of the optional properties file to be used to
              pre-specify the values of one or more variables
              in the workflow definition file.
        required: False
        type: str
        default: null
    workflow_vars:
        description:
            - Values of one or more workflow variables in JSON format.
            - >
              For example,
              C({"user_to_list":"DEBUG1", "tsocmd_to_issue":"TIME"})
        required: False
        type: dict
        default: null
    workflow_resolve_global_conflict_by_using:
        description:
            - >
              Version of the variable to be used if the supplied workflow
              variable conflicts with an existing global variable
              in z/OSMF Workflows task.
        required: False
        type: str
        default: global
        choices:
            - global
            - input
    workflow_comments:
        description:
            - >
              User-specified information to be associated with
              the workflow at creation time.
        required: False
        type: str
        default: null
    workflow_assign_to_owner:
        description:
            - >
              Specifies whether the workflow steps are assigned to
              the workflow owner when the workflow is created.
        required: False
        type: bool
        default: true
    workflow_access_type:
        description:
            - Access type for the workflow when the workflow is created.
        required: False
        type: str
        default: Public
        choices:
            - Public
            - Restricted
            - Private
    workflow_account_info:
        description:
            - >
              For a workflow that submits a batch job,
              this variable specifies the account information
              for the JCL JOB statement.
        required: False
        type: str
        default: null
    workflow_job_statement:
        description:
            - >
              For a workflow that submits a batch job,
              this variable specifies the JOB statement JCL for the job.
        required: False
        type: str
        default: null
    workflow_delete_completed_jobs:
        description:
            - >
              For a workflow that submits a batch job,
              this variable specifies whether the job is deleted
              from the JES spool after it completes.
        required: False
        type: bool
        default: false
    workflow_resolve_conflict_by_using:
        description:
            - >
              Specifies how to handle variable conflicts, if any are detected
              at workflow creation time.
            - >
              Such conflicts can be found when the z/OSMF Workflows task reads
              the output file from a step that runs a REXX exec or UNIX shell
              script.
        required: False
        type: str
        default: outputFileValue
        choices:
            - outputFileValue
            - existingValue
            - leaveConflict
    workflow_step_name:
        description:
            - >
              Name of the workflow step at which automation processing
              is to begin when the workflow is started.
        required: False
        type: str
        default: null
    workflow_perform_subsequent:
        description:
            - >
              Specifies whether the subsequent automated steps are performed
              when the workflow is started.
        required: False
        type: bool
        default: true
    workflow_notification_url:
        description:
            - >
              URL to be used for receiving notifications when the workflow is
              started.
        required: False
        type: str
        default: null
    force_complete:
        description:
            - >
              Specify whether to complete the workflow instance
              forcibly or idempotently.
            - >
              If I(force_complete=true) (Forcibly), this role will delete
              the workflow instance if it exists in the z/OSMF server,
              create a new workflow instance and start it on each target z/OS
              system, and periodically check the workflow status and return
              the final result when the workflow completes.
            - >
              If I(force_complete=false) (Idempotently),
                  - If the workflow does not exist, this role will create the workflow instance.
                  -
                    If the workflow exists but has different content(such as same workflow definition, same
                    varaible values, etc.), this role will delete the existing workflow and create a new workflow instance.
                  -
                    If the workflow exists and has consistent content(such as same workflow definition, same
                    varaible values, etc.), this workflow will be used.
            - >
              Then this role will start the workflow on each target z/OS system, and periodically
              check the workflow status and return the final result when the
              workflow completes.

        required: False
        type: bool
        default: false
    complete_check_times:
        description:
            - >
              The maximum number of checks that can be made of the workflow
              status.
        required: False
        type: int
        default: 10
    complete_check_delay:
        description:
            - >
              The interval time (in seconds) between periodic checks of the
              workflow status.
        required: False
        type: int
        default: 5
dependencies:
    - Module M(zmf_workflow)
notes:
    - >
      Submitting a z/OSMF workflow found on Ansible control node is
      currently not supported.
    - Only automated steps are supported when starting a z/OSMF workflow.
seealso:
    - module: zmf_workflow
"""

EXAMPLES = r"""
- name: sample of completing a z/OS workflow
  include_role :
    name: zmf_workflow_complete
  vars:
    workflow_name: "ansible_sample_workflow_{{ inventory_hostname }}"
    workflow_file: "/var/zosmf/workflow_def/workflow_sample_automation_steps.xml"
    force_complete: False
    complete_check_times: 10
    complete_check_delay: 5
"""

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