Skip to content

Commit

Permalink
Merge branch 'docs/cleanup-4.8' into support-4.8
Browse files Browse the repository at this point in the history
  • Loading branch information
matusmacik committed Mar 13, 2024
2 parents 6171990 + 4a63314 commit cac3c0e
Show file tree
Hide file tree
Showing 22 changed files with 341 additions and 21 deletions.
32 changes: 32 additions & 0 deletions docs/interfaces/rest/concepts/using-rest-examples.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -134,6 +134,38 @@ permit only specific actions, please have a look at this xref:/midpoint/referenc

=== Troubleshooting

==== Client Error

When the client sends a request which cannot be processed, midPoint often responds with a structure called *OperationResult*.
OperationResult contains more information, quite often a large amount of detail on the situation.

In the following example we have an operation result object returned in the case when midPoint was provided a task which should execute some action on a non-existing object.
The example is in the JSON format:

.*Example of OperationResult Returned in Case of Client Error.*
[%collapsible]
====
[source, json]
----
{
"@ns" : "http://prism.evolveum.com/xml/ns/public/types-3",
"object" : {
"@type" : "c:OperationResultType",
"operation" : "addObject",
"status" : "handled_error",
"importance" : "normal",
"start" : "2024-03-08T15:42:05.727+01:00",
"end" : "2024-03-08T15:42:05.762+01:00",
"microseconds" : 35816,
"invocationId" : 5374,
"token" : 1000000000000001288,
"message" : "Reference reportRef refers to a non-existing object dad5370f-6132-496d-8faa-6c1d3daac2b1: Object of type 'ReportType' with OID 'dad5370f-6132-496d-8faa-6c1d3daac2b1' was not found.: Reference reportRef refers to a non-existing object dad5370f-6132-496d-8faa-6c1d3daac2b1: Object of type 'ReportType' with OID 'dad5370f-6132-496d-8faa-6c1d3daac2b1' was not found.",
"partialResults" : [ ]
}
}
----
====

==== Frequent Issues

===== Missing '@' Character In Data Content File Path
Expand Down
8 changes: 8 additions & 0 deletions docs/interfaces/rest/operations/create-op-rest.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -78,8 +78,16 @@ include::../../rest/concepts/raw/outcome.adoc[]

== Access Authorization

include::../operations/raw/a-auth.adoc[]

- `+http://midpoint.evolveum.com/xml/ns/public/security/authorization-rest-3#addObject+`

== Model Authorizations

include::../operations/raw/m-auth.adoc[]

- `+http://midpoint.evolveum.com/xml/ns/public/security/authorization-model-3#add+`

== Examples

include::../raw/curl-env-note.adoc[]
Expand Down
8 changes: 8 additions & 0 deletions docs/interfaces/rest/operations/delete-op-rest.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,14 @@ include::../../rest/concepts/raw/outcome.adoc[]

== Access Authorization

include::../operations/raw/a-auth.adoc[]

- `+http://midpoint.evolveum.com/xml/ns/public/security/authorization-rest-3#deleteObject+`

== Model Authorizations

include::../operations/raw/m-auth.adoc[]

- `+http://midpoint.evolveum.com/xml/ns/public/security/authorization-rest-3#deleteObject+`

== Examples
Expand Down
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
= Access Request Review
:page-nav-title: Access Request Review
= Access Request Approval
:page-nav-title: Access Request Approval
:page-display-order: 800
:page-toc: top

Expand Down Expand Up @@ -29,7 +29,7 @@ xref:/midpoint/reference/interfaces/rest/concepts/using-rest-examples.adoc[How t
We are following up to the example described in xref:../examples/access-request.adoc[this] documentation article.

1. To be able to read the created work items the user needs to have a set of authorizations approving these actions. (See example)
2. Execute the search request as the user which wants to review his cases.
2. Execute the search request as the user which wants to execute approval action on his cases.
3. Select a specific case and *execute the action* which you would like to take with this case. #not yet implemented, please endorse this bug:MID-6067[] improvement#

[NOTE]
Expand All @@ -41,7 +41,7 @@ us with UI authorizations the second with the Model authorizations
====

.*Show* example authorization for *"Search for Open Cases For Specific Reviewer"* | link:https://raw.githubusercontent.com/Evolveum/midpoint-samples/master/samples/roles/role-authz-search-get-rest.xml[GitHub]
.*Show* example authorization for *"Search for Open Cases For Specific Approval"* | link:https://raw.githubusercontent.com/Evolveum/midpoint-samples/master/samples/roles/role-authz-search-get-rest.xml[GitHub]
[%collapsible]
====
[source, xml]
Expand Down Expand Up @@ -75,7 +75,7 @@ us with UI authorizations the second with the Model authorizations
----
====

include::../examples/raw/search-case-open-review.adoc[]
include::../examples/raw/search-case-open-approval.adoc[]

== See Also

Expand Down
27 changes: 15 additions & 12 deletions docs/interfaces/rest/operations/examples/access-request.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,11 @@ xref:/midpoint/reference/interfaces/rest/concepts/authentication/#_basic_authent

== Example

include::../../raw/curl-env-note.adoc[]
[NOTE]
====
In this example we are using the user *Jack* and authenticating with the password *y0uR_P455woR*d* on a midPoint instance running on *localhost:8080*.
This is due to the character of the example.
====

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

Expand All @@ -31,8 +35,6 @@ xref:/midpoint/reference/interfaces/rest/concepts/using-rest-examples.adoc[How t
//TODO WP#9493, some kind of redirect info should be returned here so the user is capable of watching the progress of the case
8. If you want information regarding the users case, you will have to query the open cases. A REST location header or redirect is currently missing, please see bug:MID-9493[].

include::../examples/raw/modify-attr-entitlement.adoc[]

.*Show* example authorization for *"Entitlement self request"* | link:https://raw.githubusercontent.com/Evolveum/midpoint-samples/master/samples/roles/role-authz-request-access.xml[GitHub]
[%collapsible]
====
Expand All @@ -53,7 +55,7 @@ include::../examples/raw/modify-attr-entitlement.adoc[]
<description></description>
<activation/>
<authorization>
<name>self-modify-rest</name>
<name>rest</name>
<description></description>
<action>http://midpoint.evolveum.com/xml/ns/public/security/authorization-rest-3#all</action>
</authorization>
Expand All @@ -65,10 +67,7 @@ include::../examples/raw/modify-attr-entitlement.adoc[]
<object>
<type>RoleType</type>
<filter>
<q:equal>
<q:path>requestable</q:path>
<q:value>true</q:value>
</q:equal>
<q:text>requestable = true AND parentOrgRef/@/name = "Role Catalog"</q:text>
</filter>
</object>
</authorization>
Expand All @@ -87,7 +86,7 @@ include::../examples/raw/modify-attr-entitlement.adoc[]
<target>
<type>RoleType</type>
<filter>
<q:text>requestable = true AND parentOrgRef matches (oid = "7878cf5d-9de2-486c-aeb7-41b438200a57")</q:text>
<q:text>requestable = true AND parentOrgRef/@/name = "Role Catalog"</q:text>
</filter>
</target>
<relation>org:default</relation>
Expand Down Expand Up @@ -117,9 +116,9 @@ include::../examples/raw/modify-attr-entitlement.adoc[]
</object>
<object>
<type>RoleType</type>
<filter>
<q:text>requestable = true AND parentOrgRef matches (oid = "7878cf5d-9de2-486c-aeb7-41b438200a57")</q:text>
</filter>
</object>
<object>
<type>ArchetypeType</type>
</object>
<object>
<type>UserType</type>
Expand Down Expand Up @@ -152,6 +151,10 @@ include::../examples/raw/modify-attr-entitlement.adoc[]
----
====

include::../examples/raw/search-requestable-from-role-catalog-cases.adoc[]

include::../examples/raw/modify-attr-entitlement.adoc[]

include::../examples/raw/search-case-open-user.adoc[]

== See Also
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,51 @@
:page-visibility: hidden

.*Generate Value on Input Procedure Call*
[source,bash]
----
curl --user administrator:y0uR_P455woR*d \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-X POST http://localhost:8080/midpoint/ws/rest/rpc/generate \
-v \
--data-binary @./samples/rest/policy-items-password-rpc-generate.json
----

.*Show* data source example for *"Generate value on input procedure call"* | link:https://raw.githubusercontent.com/Evolveum/midpoint-samples/master/samples/rest/policy-items-password-rpc-generate.json[GitHub]
[%collapsible]
====
By using an empty policyItemDefinition, the default value policy is used.

[source, json]
----
{
"policyItemsDefinition": {
"policyItemDefinition": {
}
}
}
----
====
The response is an HTTP 200 code in case of success *with* a response body.
.Example Output of *"Generate value on input procedure call"* example
[%collapsible]
====
[source, json]
----
{
"@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" : [ {
"value" : {
"@type" : "xsd:string",
"@value" : "3ju6We:q,DL"
}
} ]
}
}
----
====
Original file line number Diff line number Diff line change
@@ -1,16 +1,16 @@
:page-visibility: hidden
.*Search For Open Cases For Specific Reviewer*
.*Search For Open Cases For Specific Approver*
[source,bash]
----
curl --user administrator:y0uR_P455woR*d \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-X POST http://localhost:8080/midpoint/ws/rest/cases/search?options=resolveNames \
-v \
--data-binary @./samples/rest/query-asignee-review-access.json
--data-binary @./samples/rest/query-asignee-approve-access.json
----

.*Show* data source example for *"Search For Open Cases For Specific Reviewer"* | link:https://raw.githubusercontent.com/Evolveum/midpoint-samples/master/samples/rest/query-asignee-review-access.json[GitHub]
.*Show* data source example for *"Search For Open Cases For Specific Approver"* | link:https://raw.githubusercontent.com/Evolveum/midpoint-samples/master/samples/rest/query-asignee-approve-access.json[GitHub]
[%collapsible]
====
[source, json]
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,81 @@
:page-visibility: hidden
.*Search for All Requestable Objects which are a Part of the Role Catalog'*
[source,bash]
----
curl --user Jack:y0uR_P455woR*d \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-X POST http://localhost:8080/midpoint/ws/rest/roles/search \
-v \
--data-binary @./samples/rest/query-all-request-targets.json
----

.*Show* data source example for *"Search for All Requestable Objects which are a Part of the Role Catalog"* | link:https://raw.githubusercontent.com/Evolveum/midpoint-samples/master/samples/rest/query-all-request-targets.json[GitHub]
[%collapsible]
====
[source, json]
----
{
"query": {
"filter": {
"text": "requestable = true AND parentOrgRef/@/name = \"Role Catalog\""
}
}
}
----
====
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.
[%collapsible]
====
[source, json]
----
{
"@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" : "c:RoleType",
"oid" : "96262f4f-053a-4b0b-8901-b3ec01e3509c",
"version" : "5",
"name" : "employee",
"parentOrgRef" : {
"oid" : "7878cf5d-9de2-486c-aeb7-41b438200a57",
"relation" : "org:default",
"type" : "c:OrgType",
"targetName" : "Role Catalog"
},
"metadata" : {},
"operationExecution" : [],
"assignment" : {
"@id" : 3,
"metadata" : {},
"targetRef" : {
"oid" : "7878cf5d-9de2-486c-aeb7-41b438200a57",
"relation" : "org:default",
"type" : "c:OrgType",
"targetName" : "Role Catalog"
},
"activation" : {
"effectiveStatus" : "enabled"
}
},
"iteration" : 0,
"iterationToken" : "",
"roleMembershipRef" : {
"@metadata" : {},
"oid" : "7878cf5d-9de2-486c-aeb7-41b438200a57",
"relation" : "org:default",
"type" : "c:OrgType",
"targetName" : "Role Catalog"
},
"activation" : {},
"displayName" : "Basic Employee",
"requestable" : true
} ]
}
}
----
====
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ 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 \
-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.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -73,9 +73,22 @@ include::../../rest/concepts/raw/outcome.adoc[]

== Access Authorization

include::../operations/raw/a-auth.adoc[]

- `+http://midpoint.evolveum.com/xml/ns/public/security/authorization-rest-3#generateValue+`
- `+http://midpoint.evolveum.com/xml/ns/public/security/authorization-rest-3#validateValue+`

== Model Authorization

include::../operations/raw/m-auth.adoc[]

- `+http://midpoint.evolveum.com/xml/ns/public/security/authorization-model-3#get+`
- `+http://midpoint.evolveum.com/xml/ns/public/security/authorization-model-3#read+`

Additionally, for generate:

- `+http://midpoint.evolveum.com/xml/ns/public/security/authorization-model-3#modify+`

== Examples

include::../raw/curl-env-note.adoc[]
Expand Down
10 changes: 10 additions & 0 deletions docs/interfaces/rest/operations/generate-and-validate-op-rest.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -68,9 +68,17 @@ include::../../rest/concepts/raw/outcome.adoc[]

== Access Authorization

include::../operations/raw/a-auth.adoc[]

- `+http://midpoint.evolveum.com/xml/ns/public/security/authorization-rest-3#rpcGenerateValue+`
- `+http://midpoint.evolveum.com/xml/ns/public/security/authorization-rest-3#rpcValidateValue+`

== Model Authorization

include::../operations/raw/m-auth.adoc[]

No model authorizations needed in this case.

== Examples

include::../raw/curl-env-note.adoc[]
Expand All @@ -81,6 +89,8 @@ xref:/midpoint/reference/interfaces/rest/concepts/using-rest-examples.adoc[How t

include::../../rest/operations/examples/raw/validate-value-rpc.adoc[]

include::../../rest/operations/examples/raw/generate-value-rpc.adoc[]

== See Also

- xref:/midpoint/reference/interfaces/rest/concepts/media-types-rest/[Supported Media Types]
Expand Down

0 comments on commit cac3c0e

Please sign in to comment.