openapi: 3.0.0
info:
  title: Orchestration API                                   # TITLE OF THE DOCUMENT (REQUIRED)
  description: 'The Orchestration API provides programmatic access to execute orchestrations on Active Directory objects. The ADManager Plus API offers endpoints to list orchestration templates, run them against selected objects, and retrieve execution status. It enables orchestration execution to be triggered externally without requiring manual intervention from the ADManager Plus console.'  # DESCRIPTION OF THE DOCUMENT
  contact: {}
  version: 2.0.0
servers:
  -
    url: 'http://admanagerplus:8080/api/v2'                       # PRODUCT URL
    description: 'API Endpoint'                            # URL DESCRIPTION
tags:
  -
    name: orchestration                                     # TAG NAME SHOULD BE SAME AS DEFINED IN APP.YML TAGS & SAME AS YML FILE NAME (REQUIRED)
    description: 'Orchestration Endpoint'                      # DESCRIPTION ABOUT THE TAG NAME
security:
  - authToken: []
paths:
  /orchestrations  :
    get:
      tags:
        - orchestration
      summary: List orchestration templates
      description: |
        This endpoint retrieves orchestration templates configured in ADManager Plus. Results can be refined using filters, sorting, pagination, and field selection, making it easier to identify and reuse the right templates for automated tasks.
      parameters:
        - $ref: '#/components/parameters/acceptHeader'
        - $ref: '#/components/parameters/xModule'
        - $ref: '#/components/parameters/from'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/fields'
        - $ref: '#/components/parameters/filter'
        - $ref: '#/components/parameters/sort'
      responses:
        "200":
          description: Successful response with list of orchestration templates.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/list_orchestration_templates_response'
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/bad_request_response'
        "401":
          description: UnAuthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unauthorized_response'
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/internal_server_error_response'
      security: 
        - authToken:
          - Read orchestration template action, All orchestration template actions
          - delegated-roles
          - Orchestration Template
  /orchestrations/{template_id}/execute:
    post:
      tags:
        - orchestration  
      summary: Execute orchestration
      description: This endpoint executes a selected orchestration template on AD objects. It allows administrators to run predefined workflows such as user provisioning, group updates, or deprovisioning in bulk with minimal effort.
      parameters:
        - $ref: '#/components/parameters/acceptHeader'
        - $ref: '#/components/parameters/xModule'
        - $ref: '#/components/parameters/from'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/domain'
        - $ref: '#/components/parameters/filter'
        - $ref: '#/components/parameters/sort'
        - $ref: '#/components/parameters/object_type'
        - $ref: '#/components/parameters/refresh'
        - name: template_id
          in: path
          required: true
          description: 'The ID of the orchestration template that has to be executed.'
          example: 101
          schema:
            type: integer
            example: 101
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/execute_orchestration_response'
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/bad_request_response'
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unauthorized_response'
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/internal_server_error_response'
      deprecated: false
      security: 
        - authToken:
          - Run orchestration template action, All orchestration template actions
          - delegated-roles
          - Advanced Management > Orchestration
  /orchestrations/execution_status/{execution_id}:
    get:
      tags:
        - orchestration  
      summary: Get Execution status
      description: |
        This endpoint retrieves the status of a previously executed orchestration task using its execution ID. The response includes whether the task is in progress, completed, or failed, along with error details if applicable.
      parameters:
        - $ref: '#/components/parameters/acceptHeader'
        - $ref: '#/components/parameters/xModule'
        - name: execution_id
          in: path
          required: true
          description: 'The execution ID for which the status is to be retrieved.'
          example: 101
          schema:
            type: integer
            example: 101
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/execution_status_response'
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/bad_request_response'
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unauthorized_response'
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/internal_server_error_response'
      deprecated: false
      security: 
        - authToken:
          - Run orchestration template action, All orchestration template actions
          - delegated-roles
          - Advanced Management > Orchestration
components:
  parameters:
    authorization:
      name: Authorization
      in: header
      schema:
        type: string
      description: 'Authtoken for the API'
      required: true
      example: '41d**************125f'
    acceptHeader:
      name: Accept
      in: header
      schema:
        type: string
      description: 'The response format that the client accepts.'
      required: false
      example: 'application/json'
    xModule:
      name: X-Module
      in: header
      schema:
        type: string
      description: 'The module name to be recorded in the audit logs. If not provided, the default module is recorded as Rest API.'
      required: false
      example: 'External API'
    from:
      in: query
      name: from
      schema:
        type: integer
        minimum: 1
      description: 'The starting index for pagination. Enables pagination through large result sets.'
      required: false
      example: 1
    limit:
      in: query
      name: limit
      schema:
        type: integer
        maximum: 100
        minimum: 1
      description: 'The maximum number of orchestration template records to return per request.'
      required: false
      example: 50
    object_type:
      in: query
      name: object_type
      schema:
        type: string
      description: 'The type of AD object on which the orchestration template should be executed. Currently, only the user object type is supported.'
      required: true
      example: user
    fields:
      in: query
      name: fields
      schema:
        type: string
      description: '
        The attributes to be returned in the response.'
      required: false
      example: 'TEMPLATE_NAME,TEMPLATE_ID'
    filter:
      in: query
      name: filter
      schema:
        type: string
      description: >
        A SCIM filter query to refine which resources or objects are returned. See <a href="https://www.manageengine.com/uk/products/ad-manager/active-directory-api/v2/filters/#overview">Filter section</a> for details.
        <br>
        <strong>eg:</strong> (TEMPLATE_NAME eq Template1)
      required: false
      example: (TEMPLATE_NAME eq Template1)
    sort:
      in: query
      name: sort
      schema:
        type: string
      description: >
        This field is used to sort results. The default sort order is ascending. To sort in descending order, prefix the field with a hyphen (-).
        <br>
        <strong>eg:</strong> TEMPLATE_NAME
      required: false
      example: '-TEMPLATE_NAME'
    refresh:
      in: query
      name: refresh
      description: If set to true, triggers a sync before fetching results, ensuring that the data reflects the latest state of AD.
      required: false
      schema:
        type: boolean
    domain:
      in: query
      name: domain
      description: >
        The AD domain where the requested operation is performed.
        <br>
        <strong>eg:</strong> xcross.com
      required: true
      schema:
        type: string
      example: domain1.com
  schemas:
    list_orchestration_templates_response: 
      type: object
      properties:
        data:
          type: array
          example:
          - TEMPLATE_NAME: "Enable enterprise apps and notify onboarding employees"
            TEMPLATE_DESCRIPTION: "Enable Zoho CRM and send a onboarding notification"
            TEMPLATE_ID: 1
          - TEMPLATE_NAME: "Disable enterprise apps and notify offboarding employees"
            TEMPLATE_DESCRIPTION: "Disable Zoho CRM and send a offboarding notification"  
            TEMPLATE_ID: 2
        meta:
          $ref: '#/components/schemas/meta'
          example:
            start_index: 1
            limit: 10
            total_no_of_objects: 2

    templates_array:
      type: array
      items:
        example:
          - TEMPLATE_NAME: "Enable enterprise apps and notify onboarding employees"
            TEMPLATE_DESCRIPTION: "Enable Zoho CRM and send a onboarding notification"
            TEMPLATE_ID: 1
          - TEMPLATE_NAME: "Disable enterprise apps and notify offboarding employees"
            TEMPLATE_DESCRIPTION: "Disable Zoho CRM and send a offboarding notification"  
            TEMPLATE_ID: 2
    
    meta:
      type: object
      properties:
        start_index:
          type: integer
        limit:
          type: integer
        total_no_of_objects:
          type: integer

    execute_orchestration_response:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/execute_orchestration_data_response'
        meta:
          $ref: '#/components/schemas/meta'
          example:
            start_index: 1
            limit: 10
            total_no_of_objects: 1

    execute_orchestration_data_response:
      type: object
      properties:
        object:
          type: object
          $ref: '#/components/schemas/object_data'
          example:
            SAM Account Name: "TestUser1"
            Logon Name: "TestUser1@domain.com"
            Distinguished Name: "CN=TestUser1,OU=Testing OU,DC=domain,DC=com"
        status:
          $ref: '#/components/schemas/status'
          example:
            status_code: 1
            status_message: "Executing."
            execution_id: "189"

    object_data:
      type: object
      properties:
        SAM Account Name:
          type: string
        Distinguished Name:
          type: string
        Logon Name:
          type: string
    
    status:
      type: object
      properties:
        status_code:
          type: integer
        status_message:
          type: string
        execution_id:
          type: string

    execution_status_response:
      type: object
      properties:
        data:
          type: object
          properties:
            status:
              type: object
              $ref: '#/components/schemas/status'
              example:
                status_code: 1
                status_message: "Completed Successfully."

                
    bad_request_response:
      type: object
      properties:
        code:
          type: string
          description: Error code
          example: "00000100"
        detail:
          type: string
          description: Detailed error message
          example: "Some columns given in fields parameter are invalid"
        title:
          type: string
          description: Short error message
          example: "Bad Request."
    unauthorized_response:
      type: object
      properties:
        code:
          type: string
          description: Error code
          example: "00000101"
        detail:
          type: string
          description: Detailed error message
          example: "The given Authtoken is invalid."
        title:
          type: string
          description: Short error message
          example: "Unauthorized."
    internal_server_error_response:
      type: object
      properties:
        code:
          type: string
          description: Error code
          example: "00000000"
        detail:
          type: string
          description: Detailed error message
          example: "An internal server error occurred."
        title:
          type: string
          description: Short error message
          example: "Internal Server Error."
  securitySchemes:
    authToken:
      type: apiKey
      in: header
      name: Authorization
