Merge remote-tracking branch 'origin/master' into feature/mini-full-o…

…bjects

docs/concepts/query/midpoint-query-language/errors/index.adoc

@@ -52,6 +52,38 @@ a| * Verify, that the attribute is present in the object type you are searching.
 * Verify, that the view is displaying the object type you want to search. You can see its name at the end of the error message.
 |====
 
+=== Path is not present in type - dereferencing
+
+image::err-path-is-not-present-deref.png[Error path is not present - dereferencing]
+
+Another kind of the "path is not present in type" error can occur while searching in referenced objects.
+
+
+[cols="15h,50" width=85%]
+|====
+| Request
+| Find all users with assigned role identified by value "III" of identifier attribute.
+
+| Query
+| `assignment/targetRef/@ matches (identifier="III")`
+
+| Error message
+| Path identifier is not present in type {http://midpoint.evolveum.com/xml/ns/public/common/common-3}AssignmentHolderType
+
+| Reason
+a| While using dereferencing, midPoint has to know type of the referenced object to correctly process the query. +
+In this query, midPoint can't identify the type of the referenced object and incorrectly assumes it is of AssignmentHolderType.
+
+| Correct query
+| `assignment/targetRef/@ matches (. type RoleType and identifier="III")`
+
+| Troubleshooting hints
+a| * In this case you need to redefine the type of the referenced object. The code `. type RoleType` tells midPoint that type of the referenced object is RoleType. MidPoint then can find `identifier` attribute correctly.
+* When the type is explicitly defined, midPoint knows the actual schema of the object. It means, that you can search extension attributes as well. +
+E.g. the `assignment/targetRef/@ matches (. type RoleType and extension/sapType="SAP555")` is valid query when the sapType extension attribute was defined in extension schema.
+|====
+
+
 === Definition is not property
 
 image:err-definition-is-not-property.png[Error definition is not property]
@@ -81,62 +113,57 @@ a| * Verify, that the attribute is present in the object type you are searching.
 |====
 
 
-=== Cannot find enum value for string
+=== Additional unsupported filter specified
 
-image:err-cannot-find-enum-value.png[Error cannot find enum value foe string]
+image:err-add-unsupported-filter.png[Error additional unsupported filter specified]
 
 [cols="15h,50" width=85%]
 |====
 | Request
-| Find all users with normal lockout status.
+| Find all assignments of a role.
 
 | Query
-| `activation/lockoutStatus = "Normal"`
+| `assignment/targetRef matches (name="ABC:Admin")`
 
 | Error message
-| Cannot find enum value for string *'Normal'* in class com.evolveum.midpoint.xml.ns._public.common.common_3.*LockoutStatusType*
+| Additional unsupported filter specified: name="ABC:Admin"
 
 | Reason
-a| The schema defines enumerated value for this attribute. In this case the allowed values are "normal" and "locked". All lowercase.
+a| Query should be searching in referenced objects but the dereferencing operator `@` is missing.
 
 | Correct query
-a| `activation/lockoutStatus = "normal"`
+a| `assignment/targetRef/@ matches (name="ABC:Admin")`
 
 | Troubleshooting hints
-a| * Search for allowed values in schema definition. Schemas are described in
-xref:../../../../schema/schemadoc.adoc[SchemaDoc].
-Select version according your midPoint version. +
-In this case search in schema "common/common-3" for "LockoutStatusType"
-
-// Alternatively, you can search midPoint schema files #on github# for verification.
-// TODO - for this case - linka na github na schema file.
+a|
 |====
 
 
+=== Cannot find enum value for string
 
-//=== Unknown type for conversion
-// in audit search
+image:err-cannot-find-enum-value.png[Error cannot find enum value for string]
 
-////
 [cols="15h,50" width=85%]
 |====
 | Request
-|
+| Find all users with normal lockout status.
 
 | Query
-|
+| `activation/lockoutStatus = "Normal"`
 
-| Error
-|
+| Error message
+| Cannot find enum value for string *'Normal'* in class com.evolveum.midpoint.xml.ns._public.common.common_3.*LockoutStatusType*
 
 | Reason
-a|
+a| The schema defines enumerated value for this attribute. In this case the allowed values are "normal" and "locked". All lowercase.
 
 | Correct query
-|
+| `activation/lockoutStatus = "normal"`
 
 | Troubleshooting hints
-a|
-|====
-////
+a| * Search for allowed values in schema definition. Schemas are described in
+xref:../../../../schema/schemadoc.adoc[SchemaDoc].
+Select version according your midPoint version. +
+In this case search in schema "common/common-3" for "LockoutStatusType"
 
+|====

docs/concepts/query/query-concepts/index.adoc

@@ -705,11 +705,10 @@ There are the following complex filters:
 
 And, Or and Not filters are quite self-explanatory.
 
-// TODO examples
 
 ==== Type filter
 
-Type filter with parameters `type` and optional `filter` accepts iff the object is of type `type` and `filter` passes on the object.
+Type filter with parameters `type` and optional `filter` accepts if the object is of type `type` and `filter` passes on the object.
 
 For example, imagine that the original query asked for an ObjectType.
 Then it is possible to set up Type filter with type=UserType, filter=(name equals "xyz") to find only users with the name of "xyz":
@@ -730,7 +729,7 @@ Then it is possible to set up Type filter with type=UserType, filter=(name equal
 
 ==== Exists filter
 
-Exists filter with parameters `item` and optional `filter` accepts iff there exists a value
+Exists filter with parameters `item` and optional `filter` accepts if there is a value
 in the specified `item` and the value matches the provided `filter`.
 Exists inner filter works for container items and reference targets; reference targets are supported only in the repository.
 
@@ -1331,11 +1330,11 @@ This filter is supported only for the xref:/midpoint/reference/repository/native
 |===
 | Subelement | Description
 
-| `type` | type of the referencing object/container (the object pointing to the searched object), mandatory
+| `@type` | type of the referencing object/container (the object pointing to the searched object), mandatory
 
-| `path` | item path from the referencing object to the searched object, mandatory
+| `@path` | item path from the referencing object to the searched object, mandatory
 
-| `relation` | Optional filter for relation of the reference pointing to the searched object.
+| `@relation` | Optional filter for relation of the reference pointing to the searched object.
 If not stated, any relation matches (equivalent of `q:any`).
 
 | `filter` | Optional nested filter applied to the referencing object (not the objects we search for).

docs/interfaces/rest/resource-types/organizational-units.adoc → docs/interfaces/rest/endpoints/organizational-units.adoc

@@ -69,14 +69,18 @@ include::../operations/examples/raw/modify-id-generate.adoc[]
 
 - xref:/midpoint/reference/interfaces/rest/operations/generate-and-validate-concrete-op-rest/[Generate and Validate Operations]
 
+== Common Use-case Examples
+
+1.
+
 == JSON Example
 
 Example output of information regarding a specific object. Some data vas omitted to simplify the example.
 
 .Show JSON Example
 [%collapsible]
 ====
-[source, http]
+[source, json]
 ----
 {
   "org" : {

docs/interfaces/rest/endpoints/resources.adoc

@@ -0,0 +1,187 @@
+= Resource Type
+:page-nav-title: Resource
+:page-display-order: 700
+:page-toc: top
+
+== Description
+
+Here we are describing the Resource object type in relation to midPoints REST API. The
+Resource objects are a part of the REST API web resources.
+
+.Endpoint
+[source, http]
+----
+resources/
+----
+
+== Operations And Examples
+
+The Resource 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.
+
+=== Create Resource Objects
+
+include::../operations/examples/raw/create-resource.adoc[]
+
+- xref:/midpoint/reference/interfaces/rest/operations/create-op-rest/[Create Operation]
+
+=== Get Resource Type Objects
+
+Get operation for fetching a single specific object.
+
+.Get Resource Type object with REST
+
+include::../operations/examples/raw/get-resource.adoc[]
+
+- xref:/midpoint/reference/interfaces/rest/operations/get-op-rest/[Get Operation]
+
+=== Search for Resource Type Objects
+
+Search operation usable for fetching the full list of objects or a list based on filter.
+
+include::../operations/examples/raw/search-all-resource.adoc[]
+
+include::../operations/examples/raw/search-all.adoc[]
+
+- xref:/midpoint/reference/interfaces/rest/operations/search-op-rest/[Search Operation]
+
+=== Modify Resource Type Objects
+
+include::../operations/examples/raw/modify-attr-resource.adoc[]
+
+include::../operations/examples/raw/modify-attr-res-cap.adoc[]
+
+- xref:/midpoint/reference/interfaces/rest/operations/modify-op-rest/[Modify Operation]
+
+=== Delete Resource Type Objects
+
+include::../operations/examples/raw/delete-resource.adoc[]
+
+- xref:/midpoint/reference/interfaces/rest/operations/delete-op-rest/[Delete Operation]
+
+=== Generate and Validate Operations for Resource Type Objects
+
+Operations to generate or validate values.
+
+- xref:/midpoint/reference/interfaces/rest/operations/generate-and-validate-concrete-op-rest/[Generate and Validate Operations]
+
+=== Operations specific for Resources
+
+include::../operations/examples/raw/test-resource.adoc[]
+
+include::../operations/examples/raw/import-from-resource.adoc[]
+
+- xref:/midpoint/reference/interfaces/rest/operations/resource-op-rest.adoc[Resource Specific Operations]
+
+== Common Use-case Examples
+
+1.
+
+== JSON Example
+
+Example output of information regarding a specific object. Some data vas omitted to simplify the example.
+
+.Show JSON Example
+[%collapsible]
+====
+[source, json]
+----
+{
+  "resource" : {
+    "oid" : "ef2bc95b-76e0-59e2-86d6-9999cccccccc",
+    "version" : "1",
+    "name" : "Test CSV: username",
+    "description" : "Simple CSV resource that is using single identifier (username)",
+    "metadata" : {},
+    "operationExecution" : {},
+    "iteration" : 0,
+    "iterationToken" : "",
+    "connectorRef" : {
+      "oid" : "01aa0a9e-dfe0-47c8-8fca-4446894a348c",
+      "relation" : "org:default",
+      "type" : "c:ConnectorType",
+      "filter" : {
+        "equal" : {
+          "path" : "c:connectorType",
+          "value" : "com.evolveum.polygon.connector.csv.CsvConnector"
+        }
+      }
+    },
+    "connectorConfiguration" : {
+      "@ns" : "http://midpoint.evolveum.com/xml/ns/public/connector/icf-1/connector-schema-3",
+      "configurationProperties" : {
+        "@ns" : "http://midpoint.evolveum.com/xml/ns/public/connector/icf-1/bundle/com.evolveum.polygon.connector-csv/com.evolveum.polygon.connector.csv.CsvConnector",
+        "multivalueDelimiter" : ";",
+        "fieldDelimiter" : ",",
+        "filePath" : "target/midpoint.csv",
+        "encoding" : "utf-8",
+        "passwordAttribute" : "password",
+        "uniqueAttribute" : "username"
+      }
+    },
+    "schemaHandling" : {
+      "objectType" : {
+        "@id" : 1,
+        "displayName" : "Default Account",
+        "default" : true,
+        "objectClass" : "ri:AccountObjectClass",
+        "attribute" : [ {
+          "@id" : 2,
+          "ref" : "ri:username",
+          "outbound" : {
+            "source" : {
+              "path" : "$user/name"
+            }
+          }
+        }, {
+          "@id" : 3,
+          "ref" : "ri:firstname",
+          "outbound" : {
+            "source" : {
+              "path" : "$user/givenName"
+            }
+          }
+        }, {
+          "@id" : 4,
+          "ref" : "ri:lastname",
+          "outbound" : {
+            "source" : {
+              "path" : "$user/familyName"
+            }
+          }
+        } ],
+        "activation" : {
+          "administrativeStatus" : {
+            "outbound" : {
+              "@id" : 5
+            }
+          }
+        },
+        "credentials" : {
+          "password" : {
+            "outbound" : {
+              "@id" : 6
+            }
+          }
+        }
+      }
+    },
+    "capabilities" : {
+      "configured" : {
+        "activation" : {
+          "status" : {
+            "attribute" : "ri:disabled",
+            "enableValue" : "false",
+            "disableValue" : "true"
+          }
+        }
+      }
+    }
+  }
+}
+----
+====
+
+== See Also
+- xref:/midpoint/reference/interfaces/rest/concepts/media-types-rest/[Supported Media Types]
+- xref:/midpoint/reference/interfaces/rest/concepts/authentication/[Authentication]

docs/interfaces/rest/resource-types/roles.adoc → docs/interfaces/rest/endpoints/roles.adoc

@@ -70,14 +70,18 @@ include::../operations/examples/raw/modify-id-generate.adoc[]
 
 - xref:/midpoint/reference/interfaces/rest/operations/generate-and-validate-concrete-op-rest/[Generate and Validate Operations]
 
+== Common Use-case Examples
+
+1.
+
 == JSON Example
 
 Example output of information regarding a specific object. Some data vas omitted to simplify the example.
 
 .Show JSON Example
 [%collapsible]
 ====
-[source, http]
+[source, json]
 ----
 {
   "role" : {