Skip to main content

Approval Task Instance Web Services

Universal Controller supports the following RESTful-based web services for Approval Task Instance operations, which are listed alphabetically on this page.

Formatting specifications for each web service, including details about parameter requirements, are provided.

Issue Approve Command for an Approval Task Instance​

Description

URI

http://host_name/uc/resources/taskinstance/approval/approve

HTTP Method

PUT

Description

Issues an Approve command for an Approval Task instance.

Example URI

http://localhost:8080/uc/resources/taskinstance/approval/approve?taskinstanceid=1744445953815177589TYU3MFC5M5DJK

http://localhost:8080/uc/resources/taskinstance/approval/approve?taskinstancename=approval-task&criteria=3

Authentication

HTTP Basic

Produces Content-Type

application/json

Consumes Content-Type

N/A

URI Parameters

See Issue Approve Command for an Approval Task Instance: URI Parameters, below.

Response Properties

See Approval Task Properties.

Example Request Body

You can optionally specify a reason for the approval in the request body. This will be saved as a memo for the task instance.

Text/Plain
Approval reason

Example Responses

  • Status 200
    JSON
    JSON
    {
        "status": "success",
        "info": [
            {
                "message": "Command Approve executed successfully against task instance \"app\"."
            },
            {
                "message": "Approved by user {Administrator}."
            },
            {
                "message": "1 approver(s) pending."
            }
        ],
        "approverStatus": [
            {
                "type": "User",
                "name": "1",
                "status": "Pending",
                "reviewedBy": null
            },
            {
                "type": "User",
                "name": "ops.admin",
                "status": "Approved",
                "reviewedBy": "ops.admin"
            }
        ]
    }
  • Status 400
    • Command Approve failed to execute because the task instance type is incorrect.
    • Command Approve failed to execute against <taskinstancename> because it is not supported for status <status>.
    • User '<username>' is not a qualifying approver nor belong to a qualifying approver group.
      JSON
      JSON
      {
          "status": "error",
          "errors": [
              {
                  "message": "User '2' is not a qualifying approver nor belong to a qualifying approver group."
              }
          ]
      }
  • Status 404
    • No match found for task instance name "<taskinstancename>".
  • Status 403
    • Operation prohibited due to security constraints.

Issue Approve Command for an Approval Task Instance: URI Parameters​

Property

UI Field Name

Description

Specifications

Required

Mutually Exclusive With

criteria

N/A

Used if taskinstancename is specified; Specific task instance with this taskinstancename.

String; URI parameter. Valid values:

  • As String = Oldest Active Instance, As Value = 1
  • As String = Newest Active Instance, As Value = 2
  • As String = Oldest Instance, As Value = 3
  • As String = Newest Instance, As Value = 4

Default is Oldest Active Instance (1).

N

taskinstanceid

UUID

UUID of the task instance you want to approve.

String; URI parameter.

Y
(unless taskinstancename is specified.)

taskinstancename

taskinstancename

Instance Name

Name of the task instance you want to approve.

String; URI parameter.

Y
(unless taskinstanceid is specified.)

taskinstanceid

workflowinstancename

Workflow

Name of the parent Workflow of the task instance.

You can select to display the Workflow field on the Activity Monitor and/or Task Instances List; it is not displayed in the Task Instance Details.

N

Issue Reject Command for an Approval Task Instance​

Description

URI

http://host_name/uc/resources/taskinstance/approval/reject

HTTP Method

PUT

Description

Issues a Reject command for an Approval Task instance.

Example URI

http://localhost:8080/uc/resources/taskinstance/approval/reject?taskinstanceid=1744445953815177589TYU3MFC5M5DJK

http://localhost:8080/uc/resources/taskinstance/approval/reject?taskinstancename=approval-task&criteria=3

Authentication

HTTP Basic

Produces Content-Type

application/json

Consumes Content-Type

N/A

URI Parameters

See Issue Reject Command for an Approval Task Instance: URI Parameters, below.

Response Properties

See Approval Task Properties.

Example Request Body

You can optionally specify a reason for the rejection in the request body. This will be saved as a memo for the task instance.

Text/Plain
Rejection reason

Example Responses

  • Status 200
    JSON
    JSON
    {
        "status": "success",
        "info": [
            {
                "message": "Command Reject executed successfully against task instance \"app\"."
            },
            {
                "message": "Rejected by user {Administrator} and on behalf of group(s) {Administrator Group}."
            },
            {
                "message": "Approval criteria can no longer be met by approver(s)."
            }
        ],
        "approverStatus": [
            {
                "type": "User",
                "name": "ops.admin",
                "status": "Rejected",
                "reviewedBy": "ops.admin"
            },
            {
                "type": "Group",
                "name": "Administrator Group",
                "status": "Rejected",
                "reviewedBy": "ops.admin"
            }
        ]
    }
  • Status 400
    • Command Reject failed to execute because the task instance type is incorrect.
    • Command Reject failed to execute against <taskinstancename> because it is not supported for status <status>.
    • User '<username>' is not a qualifying approver nor belong to a qualifying approver group.
      JSON
      JSON
      {
          "status": "error",
          "errors": [
              {
                  "message": "Command Reject failed to execute against app because it is not supported for status REJECTED."
              }
          ]
      }
  • Status 404
    • No match found for task instance id <taskinstanceid>.
  • Status 403
    • Operation prohibited due to security constraints.

Issue Reject Command for an Approval Task Instance: URI Parameters​

Property

UI Field Name

Description

Specifications

Required

Mutually Exclusive With

criteria

N/A

Used if taskinstancename is specified; Specific task instance with this taskinstancename.

String; URI parameter. Valid values:

  • As String = Oldest Active Instance, As Value = 1
  • As String = Newest Active Instance, As Value = 2
  • As String = Oldest Instance, As Value = 3
  • As String = Newest Instance, As Value = 4

Default is Oldest Active Instance (1).

N

taskinstanceid

UUID

UUID of the task instance you want to reject.

String; URI parameter.

Y
(unless taskinstancename is specified.)

taskinstancename

taskinstancename

Instance Name

Name of the task instance you want to reject.

String; URI parameter.

Y
(unless taskinstanceid is specified.)

taskinstanceid

workflowinstancename

Workflow

Name of the parent Workflow of the task instance.

You can select to display the Workflow field on the Activity Monitor and/or Task Instances List; it is not displayed in the Task Instance Details.

N