openapi: 3.0.1
info:
  title: Workflow Approval API
  description: >
    This is the RESTful API for a user to manage pending approvals in the WSO2
    Identity Server. This API can be used to retrieve pending approvals and
    update the status of the approval tasks for the authenticated user.
  version: v1
servers:
  - url: https://{serverUrl}/t/{tenantDomain}/api/users/v1
    variables:
      serverUrl:
        default: localhost:9443
      tenantDomain:
        default: carbon.super
security:
  - OAuth2: []
  - BasicAuth: []
tags:
  - name: me
    description: Operations for the authenticated user.
paths:
  /me/approval-tasks:
    get:
      tags:
        - me
      summary: Retrieves available approvals for the authenticated user
      description: >
        Retrieve the available approval tasks in the system for the
        authenticated user. This API returns the following types of approvals:
          * READY - Tasks that are _claimable_ by the user. If a particular task is in the READY state, the user is eligible to assign the task to themself and complete it.
          * RESERVED -  Tasks that are _assigned_ to the user and to be approved by this user.
          * COMPLETED - Tasks that are already _completed_ (approved or denied) by this user.

        <b>Permission required:</b>
        `/permission/admin/manage/humantask/viewtasks` <br>

        <b>Scope required:</b> `internal_humantask_view` <br>


        A user can also invoke the endpoint with the following query parameters.
      operationId: listApprovalTasksForLoggedInUser
      parameters:
        - name: limit
          in: query
          description: Maximum number of records to return
          schema:
            minimum: 0
            type: integer
            format: int32
        - name: offset
          in: query
          description: Number of records to skip for pagination
          schema:
            minimum: 0
            type: integer
            format: int32
        - name: status
          in: query
          description: |
            Approval task's status to filter tasks by their status:
             * **RESERVED** - Tasks that are **assigned to** the authenticated user.
             * **READY** - Tasks that **can be assigned to** and **can be approved by** the authenticated user.
             * **COMPLETED** - Tasks that are **completed by** the user
             * \<empty\> - **All** the viewable tasks will be retrieved if this parameter is not specified.
          style: form
          explode: false
          schema:
            type: array
            items:
              type: object
      responses:
        '200':
          description: Array of approval tasks matching the search criteria
          content:
            '*/*':
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TaskSummary'
            application/json:
              example:
                - id: '453'
                  name: >-
                    {http://ht.bpel.mgt.workflow.identity.carbon.wso2.org}testTask
                  presentationSubject: Update Claims
                  presentationName: SampleWorkflowTask
                  taskType: TASK
                  status: RESERVED
                  priority: 0
                  createdTimeInMillis: '1565597712157'
                - id: '452'
                  name: >-
                    {http://ht.bpel.mgt.workflow.identity.carbon.wso2.org}testTask
                  presentationSubject: Update Claims
                  presentationName: SampleWorkflowTask
                  taskType: TASK
                  status: COMPLETED
                  priority: 0
                  createdTimeInMillis: '1565597675414'
                - id: '451'
                  name: >-
                    {http://ht.bpel.mgt.workflow.identity.carbon.wso2.org}testTask
                  presentationSubject: Update Claims
                  presentationName: SampleWorkflowTask
                  taskType: TASK
                  status: READY
                  priority: 0
                  createdTimeInMillis: '1565597569021'
        '400':
          description: Invalid input request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content: {}
        '403':
          description: Resource Forbidden
          content: {}
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Error'
      x-codeSamples:
        - lang: Curl
          source: |
            curl -X 'GET' \
            'https://localhost:9443/api/users/v1/me/approval-tasks' \
            -H 'accept: */*' \
            -H 'Authorization: Basic YWRtaW46YWRtaW4='
  /me/approval-tasks/{task-id}:
    get:
      tags:
        - me
      summary: Retrieve an approval task by the task-id
      description: >
        Retrieves information of a specific approval task identified by the
        task-id <br/>

        <b>Permission required:</b>
        `/permission/admin/manage/humantask/viewtasks`

        <b>Scope required:</b> `internal_humantask_view`
      operationId: getApprovalTaskInfo
      parameters:
        - name: task-id
          in: path
          description: Task ID
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Detailed information of the approval task identified by the task-id.
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/TaskData'
            application/json:
              example:
                id: '452'
                subject: Update Claims
                description: >-
                  You have a request to approve the claim update action of a
                  user.
                priority: 0
                initiator: admin
                approvalStatus: APPROVE
                assignees:
                  - key: group
                    value: admin
                properties:
                  - key: REQUEST ID
                    value: 34172334-fccb-4ef4-9830-08c3caeaab9e,
                  - key: Username
                    value: aysh234,
                  - key: User Store Domain
                    value: PRIMARY,
                  - key: Profile
                    value: default,
                  - key: Claims
                    value: >-
                      http://wso2.org/claims/organization:,http://wso2.org/claims/telephone:,http://wso2.org/claims/im:,http://wso2.org/claims/country:Sri
                      Lanka,http://wso2.org/claims/mobile:,http://wso2.org/claims/emailaddress:ayesha@wso2.com,profileConfiguration:default,http://wso2.org/claims/lastname:Dissanayaka,http://wso2.org/claims/url:,http://wso2.org/claims/givenname:Ayesha,
        '400':
          description: Invalid input request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content: {}
        '403':
          description: Resource Forbidden
          content: {}
        '404':
          description: The specified resource is not found
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Element Already Exists
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Error'
      x-codeSamples:
        - lang: Curl
          source: |
            curl -X 'GET' \
            'https://localhost:9443/api/users/v1/me/approval-tasks/451' \
            -H 'accept: */*' \
            -H 'Authorization: Basic YWRtaW46YWRtaW4='
  /me/approval-tasks/{task-id}/state:
    put:
      tags:
        - me
      summary: Changes the state of an approval task
      description: >
        Update the approval task status by defining one of the following
        actions:
         * CLAIM - Reserve the task for the user. The status of the task will be changed from READY to RESERVED.
         * RELEASE - Release the task for other users to claim. The status of the task will be changed from RESERVED to READY.
         * APPROVE - Approve the task. The status of the task will be changed to COMPLETED.
         * REJECT - Deny the task. The status of the task will be changed to COMPLETED.
         <br/>

        <b>Permission required:</b>
        `/permission/admin/manage/humantask/viewtasks`

        <b>Scope required:</b> `internal_humantask_view`
      operationId: updateStateOfTask
      parameters:
        - name: task-id
          in: path
          description: Task ID
          required: true
          schema:
            type: string
      requestBody:
        description: To which state the task should be changed.
        content:
          '*/*':
            schema:
              $ref: '#/components/schemas/State'
        required: false
      responses:
        '200':
          description: OK
          content: {}
        '400':
          description: Invalid input request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content: {}
        '403':
          description: Resource Forbidden
          content: {}
        '404':
          description: The specified resource is not found
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Error'
      x-codeSamples:
        - lang: Curl
          source: |
            curl -X 'PUT' \
            'https://localhost:9443/api/users/v1/me/approval-tasks/451/state' \
            -H 'accept: */*' \
            -H 'Authorization: Basic YWRtaW46YWRtaW4=' \
            -H 'Content-Type: */*' \
            -d '{
              "action": "APPROVE"
            }'
      x-codegen-request-body-name: next-state
components:
  schemas:
    TaskSummary:
      type: object
      properties:
        id:
          type: string
          description: Unique ID to represent an Approval Task
          example: '451'
        name:
          type: string
          description: Unique name for the Approval Task
          example: s367:testTask
        presentationSubject:
          type: string
          description: Display value for Approval Operation
          example: Add new Role
        presentationName:
          type: string
          description: Display value for Approval Task
          example: sampleTask
        taskType:
          type: string
          description: Type of the Approval
          example: TASK
        status:
          type: string
          description: State of the Approval task
          example: READY
          enum:
            - READY
            - RESERVED
            - COMPLETED
        priority:
          type: integer
          description: Priority of the Approval task
          example: 0
        createdTimeInMillis:
          type: string
          description: The time that the operation for approval initiated
          example: '1565597569021'
    TaskData:
      type: object
      properties:
        id:
          type: string
          description: Unique ID to represent an approval task.
          example: '451'
        subject:
          type: string
          description: Subject of the Approval.
          example: Add new Role
        description:
          type: string
          description: Description of the Approval task.
          example: Adds a new role to the system
        priority:
          type: integer
          description: Priority of the Approval task.
          example: 0
        initiator:
          type: string
          description: The user who initiated the task.
          example: some-user-name
        approvalStatus:
          type: string
          description: >
            Available only for the completed Tasks, APPROVED or REJECTED if the
            task has been completed, PENDING otherwise.
          example: APPROVE
          enum:
            - PENDING
            - APPROVED
            - REJECTED
        assignees:
          type: array
          description: |
            To whom the task is assigned:
              * user - username(s) if the task is reserved for specific user(s).
              * group - role name(s) if the task is assignable for group(s).
          items:
            $ref: '#/components/schemas/Property'
        properties:
          type: array
          items:
            $ref: '#/components/schemas/Property'
    Property:
      type: object
      properties:
        key:
          type: string
        value:
          type: string
    State:
      type: object
      properties:
        action:
          type: string
          description: Action to perform on the task.
          example: APPROVE
          enum:
            - CLAIM
            - RELEASE
            - APPROVE
            - REJECT
    Error:
      required:
        - code
        - message
      type: object
      properties:
        code:
          type: string
          example: some_error_code
        message:
          type: string
          example: Some Error Message
        description:
          type: string
          example: Some Error Description
        traceId:
          type: string
          example: Some Correlation for Error Instance
  responses:
    Conflict:
      description: Element Already Exists
      content:
        '*/*':
          schema:
            $ref: '#/components/schemas/Error'
    Created:
      description: Item Created
      content: {}
    Deleted:
      description: Item Deleted
      content: {}
    Forbidden:
      description: Resource Forbidden
      content: {}
    InvalidInput:
      description: Invalid input request
      content:
        '*/*':
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The specified resource is not found
      content:
        '*/*':
          schema:
            $ref: '#/components/schemas/Error'
    OK:
      description: OK
      content: {}
    ServerError:
      description: Internal Server Error
      content:
        '*/*':
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Unauthorized
      content: {}
  parameters:
    taskIdPathParam:
      name: task-id
      in: path
      description: Task ID
      required: true
      schema:
        type: string
    offsetQueryParam:
      name: offset
      in: query
      description: Number of records to skip for pagination
      schema:
        minimum: 0
        type: integer
        format: int32
    limitQueryParam:
      name: limit
      in: query
      description: Maximum number of records to return
      schema:
        minimum: 0
        type: integer
        format: int32
    statusQueryParam:
      name: status
      in: query
      description: |
        Approval task's status to filter tasks by their status:
         * **RESERVED** - Tasks that are **assigned to** the authenticated user.
         * **READY** - Tasks that **can be assigned to** and **can be approved by** the authenticated user.
         * **COMPLETED** - Tasks that are **completed by** the user
         * \<empty\> - **All** the viewable tasks will be retrieved if this parameter is not specified.
      style: form
      explode: false
      schema:
        type: array
        items:
          type: object
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://localhost:9443/oauth2/authorize
          tokenUrl: https://localhost:9443/oauth2/token
          scopes: {}
