Merge branch 'docs/cleanup-4.8' into support-4.8

docs/correlation/index.adoc

@@ -188,6 +188,42 @@ An example:
 </archetype>
 ----
 
+
+==== Example 4: Correlation for outbound resources
+
+Smart correlation relies on inbound mapping converting resource's attribute to a property of midPoint object.
+Such approach is perfect for inbound resources because it simplifies the configuration.
+Nevertheless, there are use cases with strictly outbound resource with existing accounts that need to be correlater.
+In such cases having an inbound mapping is not desired.
+
+For this situation midPoint supports the option to configure mapping for evaluation only for correlation and not for "standard" processing (by clockwork).
+
+.Listing 4. use inbound mapping only for correlation
+[source,xml]
+----
+<schemaHandling>
+    <objectType>
+        ...
+        <attribute>
+            <ref>icfs:name</ref>
+            <correlator/>
+            <inbound>
+                <target>
+                    <path>name</path>
+                </target>
+                <use>correlation</use> <!--1-->
+            </inbound>
+            <outbound> <!--2-->
+                ...
+            </outbound>
+        </attribute>
+        ...
+    </objectType>
+</schemaHandling>
+----
+<1> Means that the inbound mapping will be used only for correlation and otherwise won't be processed
+<2> Represents the outbound mapping as usual
+
 == Advanced Concepts
 
 === Multiple Correlation Rules

docs/correlation/items-correlator.adoc

@@ -1,18 +1,12 @@
 = The `items` Correlator
 :page-toc: top
-:page-since: "4.6"
-:page-upkeep-status: orange
 
-// TODO: modify to reflect that this is not a new mechanisms any more (e.g remove "newly-introduced")
-// describe correlators as a primary correlation mechanism
-// Missing: general introduction to correlation
 
 == Introduction
 
-In earlier versions of midPoint, the only correlation mechanism available was the filter-based one.
-The administrator had to specify a query based (typically) on the values of the resource object and executed it in order to find its owner.
-
-The newly-introduced `items` correlator makes this process much easier by constructing the filter(s) automatically from the correlator configuration.
+The `items` correlator uses existing inbound mappings to simplify the correlation configuration.
+The inbound mapping converts resource's attribute to a property in midPoint schema and the correlator can simply operate on already converted value.
+In addition, correlator allows you to fine tune its behaviour.
 
 == Simple Examples
 
@@ -49,6 +43,26 @@ The following configuration matches on both `givenName` and `familyName` values,
 </correlators>
 ----
 
+The following configuration matches on either `givenName` or `familyName` values, requiring that at least one of them do match.
+See xref:/midpoint/reference/correlation/rule-composition/[rule composition] for details.
+
+.Listing 3. Matching on either given name or family name
+[source,xml]
+----
+<correlators>
+    <items>
+        <item>
+            <ref>givenName</ref>
+        </item>
+    </items>
+    <items>
+        <item>
+            <ref>familyName</ref>
+        </item>
+    </items>
+</correlators>
+----
+
 == Customizing the Search
 
 Sometimes, we need to fine-tune the search based on individual items.
@@ -89,7 +103,7 @@ But there are cases when it is needed.)
 
 An example:
 
-.Listing 3. Specifying the normalization and then using it for correlation
+.Listing 4. Specifying the normalization and then using it for correlation
 [source,xml]
 ----
 <objectTemplate>
@@ -143,7 +157,7 @@ This is especially true when dealing with values that are not indexed.
 
 For example, we may want to specify that when correlating on `employeeNumber` we want to use `mr:polyStringNorm` matching rule:
 
-.Listing 4. Specifying the matching rule used when correlating
+.Listing 5. Specifying the matching rule used when correlating
 [source,xml]
 ----
 <objectTemplate>
@@ -172,7 +186,7 @@ The fuzzy search can be specified for both custom-indexed and regular items.
 
 An example:
 
-.Listing 4. Specifying the fuzzy search used when correlating
+.Listing 6. Specifying the fuzzy search used when correlating
 [source,xml]
 ----
 <objectTemplate>
@@ -205,7 +219,7 @@ It is also possible to specify correlation search options that are to be applied
 
 For example, let us specify the default search options used when correlating by `givenName`.
 
-.Listing 5. Specifying the fuzzy search used when correlating
+.Listing 7. Specifying the fuzzy search used when correlating
 [source,xml]
 ----
 <objectTemplate>
@@ -256,7 +270,7 @@ NOTE: These search options are completely overridden when `search` element is pr
 In simple scenarios, it is possible to define single-item correlator right on the resource object attribute.
 An example:
 
-.Listing 6. `ri:employeeNumber` serving as a correlation attribute
+.Listing 8. `ri:employeeNumber` serving as a correlation attribute
 [source,xml]
 ----
 <schemaHandling>