Organizational Unit Type REST Endpoint

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

Description

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

Endpoint
orgs/

Operations And Examples

The Organizational Unit 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:

Create Organizational Unit Objects

Create a new Organizational Unit 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/orgs \
-v \
--data-binary @./samples/rest/org-project.json
Show data source example for "Create a new Organizational Unit object in MidPoint" | GitHub
{
  "org": {
    "name": "P0000",
    "displayName": "Projects"
  }
}

The response is an HTTP 201 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/orgs/e5ae2f30-141c-4990-8387-4c8e7433132d

Get Organizational Unit Objects

Get operation for fetching a single specific object.

Get Organizational Unit
curl --user administrator:y0uR_P455woR*d \
-H "Accept: application/json" \
-X GET http://localhost:8080/midpoint/ws/rest/orgs/e5ae2f30-141c-4990-8387-4c8e7433132d?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 Organizational Unit" 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.

{
  "org" : {
    "oid" : "e5ae2f30-141c-4990-8387-4c8e7433132d",
    "version" : "1",
    "name" : "P0000",
    "metadata" : {},
    "operationExecution" : {},
    "iteration" : 0,
    "iterationToken" : "",
    "activation" : {},
    "displayName" : "Projects"
  }
}

Search for Organizational Unit Objects

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

Search for All Organizational Units 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/orgs/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": {}
    } ]
  }
}

Modify Organizational Unit Objects

Modify Organizational Unit
curl --user administrator:y0uR_P455woR*d \
-H "Content-Type: application/json" \
-X PATCH http://localhost:8080/midpoint/ws/rest/orgs/e5ae2f30-141c-4990-8387-4c8e7433132d \
-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.

Delete Organizational Unit Objects

Delete an Organizational Unit type object
curl --user administrator:y0uR_P455woR*d \
-v \
-X DELETE http://localhost:8080/midpoint/ws/rest/orgs/e5ae2f30-141c-4990-8387-4c8e7433132d

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

Generate and Validate Operations for Organizational Unit Objects

Operations to generate or validate values, here we have an example of a simple identifier generate use-case.

Generate Identifier for Role Type Object
curl --user administrator:y0uR_P455woR*d \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-X POST http://localhost:8080/midpoint/ws/rest/orgs/e5ae2f30-141c-4990-8387-4c8e7433132d/generate \
-v \
--data-binary @./samples/rest/policy-items-identifier-generate.json
Show data source example for "Generate identifier for object" | GitHub
{
	"policyItemsDefinition": {
		"policyItemDefinition": {
			"target": {
				"path": "identifier"
			},
			"execute": "true"
		}
	}
}

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

Show example output for "Generate identifier for object"
{
  "@ns" : "http://prism.evolveum.com/xml/ns/public/types-3",
  "object" : {
    "@type" : "http://midpoint.evolveum.com/xml/ns/public/common/api-types-3#PolicyItemsDefinitionType",
    "policyItemDefinition" : [ {
      "target" : {
        "path" : "identifier"
      },
      "value" : {
        "@type" : "xsd:string",
        "@value" : "s2cMJrD5^21"
      },
      "execute" : true
    } ]
  }
}

Common Use-case Examples

JSON Example

Example output of information regarding a specific object. Some data vas omitted to simplify the example.

Show JSON Example
{
  "org" : {
    "oid" : "e5ae2f30-141c-4990-8387-4c8e7433132d",
    "version" : "1",
    "name" : "P0000",
    "metadata" : {},
    "operationExecution" : {},
    "iteration" : 0,
    "iterationToken" : "",
    "activation" : {},
    "displayName" : "Projects"
  }
}
Was this page helpful?
YES NO
Thanks for your feedback