Approvals via REST HOWTO

Last modified 15 Jan 2025 14:56 +01:00

The following approval-related operations are currently available via REST service:

starting an approval process,
determining the status of the approval process.
complete work item (approving or rejecting item)
delegate work item
claim work item
release work item
cancel case

In this document we’ll show how to carry out these operations.

Starting an approval process

In midPoint the approval process is started automatically when an operation requiring approval is started. I.e. there’s no special "start an approval process" method.

Let us illustrate this on an example.

This is user peter:

<user xmlns="http://midpoint.evolveum.com/xml/ns/public/common/common-3"
    oid="cac0694d-62d8-441b-a277-0a33b8caa0f7">
    <name>peter</name>
</user>

This is role sensitive that we want to assign to peter:

<role xmlns="http://midpoint.evolveum.com/xml/ns/public/common/common-3"
    oid="d4930444-c5e5-4710-af96-19f79eb078cb">
    <name>sensitive</name>
</role>

The role has an approver, named paul:

<user xmlns="http://midpoint.evolveum.com/xml/ns/public/common/common-3"
    oid="3b5b5d18-b1d9-4125-b435-a5d3aece8546">
    <name>paul</name>
    <assignment>
        <targetRef oid="d4930444-c5e5-4710-af96-19f79eb078cb" type="RoleType" relation="approver"/>
    </assignment>
    <assignment>
        <targetRef oid="00000000-0000-0000-0000-000000000004" type="RoleType"/> <!--  Superuser, to avoid authorization issues -->
    </assignment>
    <credentials>
        <password>
            <value>5ecr3t</value>
        </password>
    </credentials>
</user>

Paul has an assignment to role sensitive with a relation of approver, so it is an approver for all assignments of that role.

Now let’s start the approval process. We will do that by assigning role special to user peter.

curl.exe -v --user administrator:5ecr3t -H "Content-Type: application/xml" -X PATCH http://localhost:8080/midpoint/ws/rest/users/cac0694d-62d8-441b-a277-0a33b8caa0f7 -d @assign-sensitive-role.xml

assign-sensitive-role.xml

<objectModification
         xmlns="http://midpoint.evolveum.com/xml/ns/public/common/api-types-3"
         xmlns:t="http://prism.evolveum.com/xml/ns/public/types-3"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xmlns:c="http://midpoint.evolveum.com/xml/ns/public/common/common-3">
    <t:itemDelta>
        <t:modificationType>add</t:modificationType>
        <t:path>assignment</t:path>
        <t:value xsi:type="c:AssignmentType">
            <c:targetRef oid="d4930444-c5e5-4710-af96-19f79eb078cb" type="c:RoleType">
                <!-- sensitive -->
            </c:targetRef>
        </t:value>
    </t:itemDelta>
</objectModification>

The above XML is sent to the REST service and it will be applied (as an object delta) to object cac0694d-62d8-441b-a277-0a33b8caa0f7, i.e. peter. It has one item delta, in particular creation of an assignment to d4930444-c5e5-4710-af96-19f79eb078cb i.e. to the sensitive role.

The response is then like this:

HTTP/1.1 204
Date: Thu, 25 Oct 2018 12:31:26 GMT

I.e. the operation was successful.

Determining the status of the approval process

The approval processes are represented as case objects. So they can be retrieved just like any other using the REST search operation. An example:

get-approval-cases-for-peter.bat

curl.exe -v --user administrator:5ecr3t -H "Content-Type: application/xml" -X POST "http://localhost:8080/midpoint/ws/rest/cases/search" -d @get-approval-cases-for-peter.xml

get-approval-cases-for-peter.xml

<q:query xmlns:q="http://prism.evolveum.com/xml/ns/public/query-3">
    <q:filter>
        <q:text>objectRef matches (oid = '96262f4f-053a-4b0b-8901-b3ec01e3509c') AND state = "open"</q:text>
    </q:filter>
</q:query>

The above search query returns all approval processes and the whole requests that deal with the user cac0694d-62d8-441b-a277-0a33b8caa0f7 i.e. peter and are still waiting to be resolved (state=open condition).

Formally, state is an URI. It can have both unqualified and qualified forms, e.g. open vs http://midpoint.evolveum.com/xml/ns/public/common/case-3#open. In theory, you would need to check for both, using e.g. OR filter clause. But practically, midPoint currently uses the unqualified form.

There are two kinds of approval-related cases:

Operation-level cases, covering the whole operation. Each operation can consist of one or more elementary actions, like "add assignment to role R1", "add assignment to role R2", "remove assignment of role R3". Operation cases have the Operation request archetype.
Individual approval cases; each covering a single elementary action, like "add assignment to role R1". Each such task corresponds to a single approval process. These have the Approval case archetype.

You can use a filter on archetypeRef to differentiate between these two kinds; returning only what you need.

Approval, work item related operations are described together in REST endpoint description documentation here. This documentation also provides examples on how to use this API.

Was this page helpful?

YES NO

Thanks for your feedback

Approvals via REST HOWTO

Starting an approval process

Determining the status of the approval process

Other case/work items related operations