Task Type REST Endpoint

Last modified 13 Mar 2024 13:32 +01:00

Table of Contents

Description
Operations And Examples
Common Use-case Examples
JSON Example
See Also

Description

Here we are describing the Task object type in relation to midPoints REST API. The Task objects are a part of the REST API web resources.

Endpoint

tasks/

Operations And Examples

The Tasks endpoint is a part of the Create-Read-Update-Delete (CRUD) web resources present in midPoint. This is apparent in the operations which are available for this type of object.

In our examples we are authenticating with the credentials, name "administrator" and password "y0uR_P455woR*d" on a localhost instance running on port 8080.

For some help regarding the REST examples please see this link:

How to use MidPoint REST examples

Create Task Objects

Create a new Task object in MidPoint with file data source

curl --user administrator:y0uR_P455woR*d \
-H "Content-Type: application/json" \
-X POST http://localhost:8080/midpoint/ws/rest/tasks \
-v \
--data-binary @./samples/rest/task-recompute-members-employee.json

Show data source example for "Create a new Task object in MidPoint" | GitHub

{
  "task" : {
    "name" : "Recompute all direct members of Role Basic Employee",
    "schedulingState" : "ready",
    "binding" : "loose",
    "activity" : {
      "work" : {
        "recomputation" : {
          "objects" : {
            "type" : "UserType",
            "query" : {
              "filter" : {
                "text" : "assignment matches (targetRef matches (oid = '96262f4f-053a-4b0b-8901-b3ec01e3509c'))"
              }
            }
          }
        }
      }
    }
  }
}

The response is an HTTP 202 code in case of success without a response body. Also, the response contains a Location Header pointing to the location of the created user.

Example location header

Location: http://localhost:8080/midpoint/ws/rest/tasks/6d13632c-6b75-4a33-9744-ec9523375f6b

Create Operation

Get Task Type Objects

Get operation for fetching a single specific object.

Get Task Object

curl --user administrator:y0uR_P455woR*d \
-H "Accept: application/json" \
-X GET http://localhost:8080/midpoint/ws/rest/tasks/6d13632c-6b75-4a33-9744-ec9523375f6b?options=raw \
-v

The response is an HTTP 200 code in case of success with a response body containing the queried item.

Example Output of "Get Task Object" example

The example is simplified, some properties were removed to keep the example output "short". This example does not contain all possible properties of this object type.

{
  "task" : {
    "oid" : "6d13632c-6b75-4a33-9744-ec9523375f6b",
    "version" : "",
    "name" : "Recompute all direct members of Role Basic Employee",
    "metadata" : {},
    "operationExecution" : {},
    "assignment" : {},
    "iteration" : 0,
    "iterationToken" : "",
    "archetypeRef" : {},
    "roleMembershipRef" : {},
    "taskIdentifier" : "",
    "ownerRef" : {},
    "executionState" : "",
    "schedulingState" : "",
    "result" : {},
    "resultStatus" : "",
    "lastRunStartTimestamp" : "",
    "lastRunFinishTimestamp" : "",
    "completionTimestamp" : "",
    "progress" :,
    "operationStats" : {},
    "binding" : "loose",
    "activity" : {},
    "activityState" : {},
    "affectedObjects" : {}
  }
}

Get Operation

Search for Task Type Objects

Search operation usable for fetching the full list of objects or a list based on filter.

Search for All Tasks With Name That Starts With 'a'

curl --user administrator:y0uR_P455woR*d \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-X POST http://localhost:8080/midpoint/ws/rest/tasks/search \
-v \
--data-binary @./samples/rest/query-gen-name.json

Show data source example for "Search for name starting with 'a'" | GitHub

{
  "query": {
    "filter": {
      "text": "name startsWith \"a\""
    }
  }
}

The response is an HTTP 200 code in case of success with a response body containing the queried items.

Example Output is a list of objects.

{
  "@ns" : "http://prism.evolveum.com/xml/ns/public/types-3",
  "object" : {
    "@type" : "http://midpoint.evolveum.com/xml/ns/public/common/api-types-3#ObjectListType",
    "object" : [ {
      "@type" : "",
      "oid" : "",
      "version" : "",
      "name" : "",
      "metadata" : {},
      "operationExecution": {},
      "indestructible": ,
      "iteration" : ,
      "iterationToken" : "",
      "archetypeRef": {},
      "roleMembershipRef": {},
      "activation": {}
    }, {
      "@type" : "",
      "oid" : "",
      "version" : "",
      "name" : "",
      "metadata" : {},
      "operationExecution": {},
      "indestructible": ,
      "iteration" : ,
      "iterationToken" : "",
      "archetypeRef": {},
      "roleMembershipRef": {},
      "activation": {}
    } ]
  }
}

Search Operation

Modify Task Type Objects

Modify Tasks

curl --user administrator:y0uR_P455woR*d \
-H "Content-Type: application/json" \
-X PATCH http://localhost:8080/midpoint/ws/rest/tasks/6d13632c-6b75-4a33-9744-ec9523375f6b \
-v \
--data-binary @./samples/rest/modify-attribute-gen.json

Show data source example for "Modify attribute value" | GitHub

{
	"objectModification": {
		"itemDelta": {
			"modificationType": "add",
			"path": "description",
			"value": "Description parameter modified via REST"
		}
	}
}

The response is an HTTP 204 code in case of success without a response body.

Modify Operation

Delete Task Type Objects

Delete a Task type object

curl --user administrator:y0uR_P455woR*d \
-v \
-X DELETE http://localhost:8080/midpoint/ws/rest/tasks/6d13632c-6b75-4a33-9744-ec9523375f6b

The response is an HTTP 204 code in case of success without a response body.

Delete Operation

Generate and Validate Operations for Task Type Objects

Operations to generate or validate values.

Generate and Validate Operations

Operations specific for Tasks

Start a Task

curl --user administrator:y0uR_P455woR*d \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-v \
-X POST http://localhost:8080/midpoint/ws/rest/tasks/6d13632c-6b75-4a33-9744-ec9523375f6b/run

The response is an HTTP 204 code in case of success, without a response body.

Suspend a Running Task

curl --user administrator:y0uR_P455woR*d \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-v \
-X POST http://localhost:8080/midpoint/ws/rest/tasks/6d13632c-6b75-4a33-9744-ec9523375f6b/suspend

The response is an HTTP 204 code in case of success with a response body.

Resume a Suspended Task

curl --user administrator:y0uR_P455woR*d \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-v \
-X POST http://localhost:8080/midpoint/ws/rest/tasks/6d13632c-6b75-4a33-9744-ec9523375f6b/resume

The response is an HTTP 202 code in case of success, without a response body.

Task Specific Operations

Common Use-case Examples

JSON Example

Example output of information regarding a specific Task object. Metadata is usually a part of the output, yet it was removed for the purpose of the example.

Show JSON Example

{
  "task" : {
    "oid" : "6d13632c-6b75-4a33-9744-ec9523375f6b",
    "version" : "",
    "name" : "Recompute all direct members of Role Basic Employee",
    "metadata" : {},
    "operationExecution" : {},
    "assignment" : {},
    "iteration" : 0,
    "iterationToken" : "",
    "archetypeRef" : {},
    "roleMembershipRef" : {},
    "taskIdentifier" : "",
    "ownerRef" : {},
    "executionState" : "",
    "schedulingState" : "",
    "result" : {},
    "resultStatus" : "",
    "lastRunStartTimestamp" : "",
    "lastRunFinishTimestamp" : "",
    "completionTimestamp" : "",
    "progress" :0,
    "operationStats" : {},
    "binding" : "loose",
    "activity" : {},
    "activityState" : {},
    "affectedObjects" : {}
  }
}