Merge branch 'master' of github.com:Evolveum/docs

* 'master' of github.com:Evolveum/docs: (59 commits)
  Update protected accounts doc
  Update protected accounts doc
  continuous-integration: added notes about custom forks and new CI (WIP)
  Fix image link (?)
  Add "resource schema" minutes from 27.4.2022
  Add draft of resource templates
  Axiom query: not experimental any more
  Expanded referencedBy section
  REST API: cleanup, typo and mainly asciidoc fixes
  intellij-idea: update of picture with generated sources for schema
  Idea about bulk task generator in UI
  fist steps: more lifecycle notes
  Added writeup for query matching rule
  Book version 2.2
  Add "limitations" section to validity scan page
  First steps: refining lifecycle states
  MID-7875:adding comment for oidc provider configuration uris
  Idea about "categories" of information (mostly attributes). Better name needed.
  adding link to flex auth on self-registration page
  MID-7890:changing self-registration page after cleanup of schema
  ...

docs/admin-gui/admin-gui-config/index.adoc

@@ -12,7 +12,6 @@
 Admin GUI configuration is a specialized data structure that is present in xref:/midpoint/reference/concepts/system-configuration-object/[system configuration object], in all the role-like objects (roles, orgs, services), in the xref:/midpoint/architecture/archive/data-model/midpoint-common-schema/usertype/[user objects] and partially also in archetype objects. The admin GUI configuration structure influences how to user interface is displayed.
 Despite its name it applies both to the self-service part and administration part of the user interface.
 
-
 == Basic Structure
 
 The admin GUI configuration structure contains:
@@ -36,7 +35,6 @@ However the compatibility will be maintained and this setting will also remain h
 
 * `*feedbackMessagesHook*`: Script hook configuration which can be used to modify operation results shown in GUI.
 
-
 Since midPoint 4.4, the look and feel of GUI has been significantly changed. The aim was to provide better user experience and more configuration options. The old look is still available in midPoint for preview. It can be turned on in adminGuiConfiguration setting `useNewDesign` property to _false_. However, bugs and improvements will be fixed and implemented only for the new look and the old look will be completely removed in release 4.6. Old look is no more supported in 4.4. Please, migrate your configuration as soon as possible.
 
 == How It Works
@@ -78,6 +76,7 @@ The step that applies admin GUI configuration from the user object is meant to s
 It is only partially implemented.
 
 === Widgets
+
 The merged configurations for widgets have one quite specific characteristic.
 If no configuration is present at all, then a default configuration will be used (all default widgets).
 However, if only a single widget is defined then the default configuration is not applied.
@@ -88,6 +87,7 @@ But they are not that flexible yet.
 Therefore all the widgets need to be explicitly defined in order to appear in a customized dashboard.
 
 === Object details
+
 Object details configuration influences the look and feel of the pages for creating and editing object. MidPoint comes with default panels and default pre-defined configuration for each object available to edit and create in GUI. It is basic configuration which might be adjusted according to customer's needs. Custom configuration defined by customer is merged with default pre-defined configuration according to the rules described in _How it works_.
 
 Comparing the behavior before 4.4, there is a change in merging mechanism. Before 4.4 if any customization was made, it meant that the default configuration wasn't taken into the account while displaying the corresponding page. Since 4.4 this behavior was changed, so any custom configuration is additional to one coming with midPoint by default. If the behavior or settings of the default panel needs to be changed, it is done with adjusting such configuration. To be able to adjust and override default configuration the `identifier` have to be specified and correctly used.
@@ -114,6 +114,7 @@ Basis structure for object details configuration is:
 
 Following tables described basic configuration options for panels:
 [%autowidth]
+
 |===
 | Property | Mandatory | Type | Description
 
@@ -192,6 +193,7 @@ MidPoint itself comes with default panels with the identifiers specified. Those
 
 Panels applicable for all AssignmentHolderType object (except ResourceType):
 [%autowidth]
+
 |===
 | Panel | Identifier | Description | Default order | Panel type
 
@@ -204,6 +206,7 @@ Panels applicable for all AssignmentHolderType object (except ResourceType):
 
 Panels applicable for all FocusType objects:
 [%autowidth]
+
 |===
 | Panel | Identifier | Description | Default order
 
@@ -347,6 +350,7 @@ Panel applicable for all AbstractRoleType objects:
 
 Panels applicable only for users:
 [%autowidth]
+
 |===
 | Panel | Identifier | Description | Default order
 
@@ -502,6 +506,7 @@ Panels applicable only for object collections:
 
 Panels applicable only for object templates:
 [%autowidth]
+
 |===
 | Panel | Identifier | Description | Default order
 
@@ -545,6 +550,7 @@ Panels applicable only for reports:
 
 Panels applicable only for resources:
 [%autowidth]
+
 |===
 | Panel | Identifier | Description | Default order
 
@@ -758,12 +764,8 @@ Panels applicable only for system configuration:
 | 30
 |===
 
-
-
-
 == Examples
 
-
 === Show Only Some Default Forms
 
 Suppose you want to show only "Basic", "Password", "Activation" and "Assignment" panels in the user details page.
@@ -1153,7 +1155,6 @@ Set another panel as `basic` panel to be shown as a default panel after opening
 
 TODO:
 
-
 === Hiding User Dashboard Widgets
 
 Following example can be used to customize the look of the user dashboard (home screen).
@@ -1265,7 +1266,6 @@ Possible widget identifiers on the self dashboard page:
 
 |===
 
-
 === Custom columns configuration
 
 To customize columns in the object list table, please, see use the following example
@@ -1305,7 +1305,6 @@ To customize columns in the object list table, please, see use the following exa
 
 image::custom-columns-2022-03-18.png[]
 
-
 Column can be configured with the following attributes
 
 [%autowidth]
@@ -1360,7 +1359,6 @@ However, the algorithm should be deterministic: the same ordering should be used
 
 |===
 
-
 == Custom actions for object lists
 
 Starting from midpoint 3.9, there is a possibility to configure a custom action to be run from the object list table.
@@ -1389,7 +1387,6 @@ To configure custom actions, please, use the following example
 
 Xml for the task template object you can find by the link:https://github.com/Evolveum/midpoint-samples/blob/master/samples/tasks/templates/task-template-change-description.xml[following link]. After custom action is configured in the admin gui configuration section, you can find action link among menu items on the appropriate type object list panel.image::custom_action_screen.png[]
 
-
 == Admin GUI Configuration and Authorizations
 
 At the first sight the use of admin GUI configuration to define object forms and dashboard widgets may seem to be redundant.
@@ -1436,7 +1433,6 @@ This link will be displayed only if the user has authorization that allow the ac
 Secondly, inclusion of default forms and the `automatic` visibility mode of widgets are authorization-sensitive.
 This means that form or widget will be displayed only if the user has access to the data that are displayed.
 
-
 == Feedback Messages Hook
 
 Feedback messages hook configuration allows operation result preprocessing before it's shown in GUI.
@@ -1481,29 +1477,101 @@ To see changes made in this part of configuration, user needs to do logout/login
 </adminGuiConfiguration>
 ----
 
-== Notes
-
-=== Classpath scanning
+== Customizing classpath scanning
 
 Different panels and pages are searched via annotations on classes, e.g. `@PageDescriptor`, `@PanelInstance`, and others.
-In versions prior 4.5 (4.4.2) whole classpath was used to search for such annotated classes.
+In versions prior 4.5 (4.4.2) whole classpath was used to search for such annotated classes
+which resulted in less than ideal performance of the scanning process.
 In midPoint version 4.5 (4.4.2) and newer default search scope is package `com.evolveum.midpoint`.
-It is possible to extend search scope, for example when using maven overlay with custom code.
-Extension can be done via setting property `midpoint.additionalPackagesToScan` with comma separated package names in `${midpoint.home}/application.yml` like so:
 
-[source, yaml]
+It is possible to extend the search scope by setting the property `midpoint.additionalPackagesToScan` to comma separated package names.
+This is required for xref:/midpoint/reference/deployment/maven-overlay-project/[midPoint Overlays]
+with custom GUI pages and forms.
+
+The property can be set in one of the following ways:
+
+* Using command line argument:
+** You can use JVM argument like `-Dmidpoint.additionalPackagesToScan=my.package`.
+If using `midpoint.sh` or `start.sh`, this can be also provided with `JAVA_OPTS` environment variable.
+The variable can also be set in `setenv.sh` file (see xref:/midpoint/install/distribution/#post-installation[this] for more).
+
+** You can also use application argument `--midpoint.additionalPackagesToScan=my.package`,
+which can be provided as an argument to `midpoint.sh` or `start.sh` scripts.
+
++
+--
+Either of this can be also set in service configuration for midPoint (e.g. `ExecStart` for systemd),
+just remember that `-Dkey=val` form goes *before* the `-jar` option while `--key=val` form goes
+*after* the `-jar` option and its `midpoint.war` parameter.
+
+You can find more information in xref:/midpoint/operations-manual/#changing-the-midpoint-embedded-tomcat-configuration[this part] of the Operation manual.
+--
+
+* Using `application.yml` (or `application.properties`) file in xref:/midpoint/reference/deployment/midpoint-home-directory/[midPoint home directory].
+E.g. for YAML format the file `${midpoint.home}/application.yml` may look like this:
++
+[source,yaml]
 ----
 midpoint:
   additionalPackagesToScan: org.example.acme,com.acme
 ----
++
+This file complements the default built-in midPoint configuration.
+
+* Finally, you can add the configuration directly into the overlay project.
+This is more convenient for the user of the JAR/WAR file as they don't need to take any additional action.
+To do this you need to add properties or YAML file into the root of the classpath, which typically
+is `src/main/resources` directory.
++
+Here, a little knowlege of midPoint structure is needed, concretely - midPoint uses `application.yml` file.
+We can't put the same file into overlay's `src/main/resources` because it would overwrite the default one.
+There is a couple of options:
+
+** You can use `application.yml`, but first copy its content from midPoint sources - the file can be found in `gui/admin-gui/src/main/resources/application.yml`.
+Then put your options inside it, in case of `midpoint.additionalPackagesToScan` you can just add
+the lines (see the YAML example above) at the end.
++
+This works, but it can be annoying when upgrading the overlay to the new midPoint version
+as it may contain some changes to the default configuration which you should copy again.
+There are better ways.
+
+** Use `application-default.yml` instead - this one complements the default configuration.
+It is the same as adding `${midpoint.home}/application.yml` in the example above and the content
+of the file is exactly the same.
+This still allows using the `${midpoint.home}/application.yml` file for other purposes,
+but you don't have to worry about the GUI component scanning anymore.
+
+** Finally, knowing that midPoint uses `application.yml` and Spring Boot also recognizes
+`application.properties` you can use the latter file - which also has a bit simpler content
+(although arguably less structured):
++
+[source,properties]
+----
+midpoint.additionalPackagesToScan=org.example.acme,com.acme
+----
++
+Both YAML and properties files are merged nicely, but the option with `application-default.yml`
+is still the preferred one.
+If you really want to use properties format, name the file `application-default.properties` instead.
+That clearly shows it is an additional configuration file to complement the existing configuration.
+
+All these options use the Spring Boot mechanism called https://docs.spring.io/spring-boot/docs/current/reference/html/features.html#features.external-config[Externalized Configuration].
+
+[TIP]
+====
+Long story short - the best way to specify the property in overlay project is adding
+`application-default.yml` (or `application-default.properties`) under `src/main/resources` directory
+in your overlay project sources.
+
+See the overlay example https://github.com/Evolveum/midpoint-overlay-example/tree/master/src/main/resources[here].
+====
 
 == Security
 
 Some parts of admin GUI configuration may contain xref:/midpoint/reference/expressions/expressions/[expressions]. Expressions are pieces of code that are executed inside midPoint server.
 As such expressions has to be inherently trusted.
 Therefore do not allow untrusted users to define sensitive parts of admin GUI configuration.
 
-
 == See Also
 
 * xref:/midpoint/reference/concepts/system-configuration-object/[System Configuration Object]

docs/admin-gui/dashboards/configuration/index.adoc

@@ -36,7 +36,6 @@ Dashboard contains name, display with label and widgets.
          ...
      </widget>
      ...
-         <visibility>hidden</visibility> <!-- deprecated since 4.3, use configurableUserDashboard in adminGuiConfig instead -->
 </dashboard>
 ----
 
@@ -52,15 +51,15 @@ The configuration is show below:
 [source,xml]
 ----
 <adminGuiConfiguration>
-        ....
-        <configurableUserDashboard>
-            <identifier>admin-dashboard</identifier>
-                <display>
-                        <label>Admin dashboard</label>
-                </display>
-        <configurableDashboardRef oid="00000000-0000-0000-0001-000000000001" relation="org:default" type="c:DashboardType"/>
-                <visibility>visible</visibility>
-        </configurableUserDashboard>
+    ...
+    <configurableUserDashboard>
+        <identifier>admin-dashboard</identifier>
+        <display>
+            <label>Admin dashboard</label>
+        </display>
+        <configurableDashboardRef oid="00000000-0000-0000-0001-000000000001"/>
+        <visibility>visible</visibility>
+    </configurableUserDashboard>
 </adminGuiConfiguration>
 ----
 

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

@@ -1,6 +1,5 @@
 = Axiom Query Language
 :page-since: "4.3"
-:page-experimental: true
 :page-toc: top
 
 //TODO: User-friendly documentation of a user-friendly language.
@@ -289,9 +288,12 @@ Axiom Query Language is replacing an old xref:../xml-query-language/[XML-based q
 The new language is more natural, user-friendly and better aligned with foundations of xref:/midpoint/devel/axiom/[Axiom data modeling].
 
 Axiom query language is a relative new development, introduced in midPoint 4.3.
-It is expected to be fully supported in midPoint 4.4 LTS, where it should become a recommended option.
-The Axiom query language should replace the XML-based language as soon as possible.
-The XML-based language will be still supported for several years, but it will be dropped eventually.
+It was almost fully supported in midPoint 4.4 LTS, except for embedded expression.
+Since midPoint 4.5, Axiom query language is fully supported and recommended option.
+
+The Axiom query language is a full replacement for XML-based language.
+The XML-based language will be still supported for some time, but it will be dropped eventually.
+Users of XML-based query language should migrate to Axiom query language as soon as possible.
 
 == See Also
 

docs/diag/initial-logging.adoc

@@ -133,7 +133,7 @@ logger is set to level `DEBUG` or `TRACE` - which can be a security issue if it'
 To avoid this, values are replaced by a placeholder string.
 In rare troubleshooting situations this may be a problem and actual values must be investigated.
 
-To allow this JVM argument `-DmidpointPrintSensitiveValues` must be added to the command line,
+To allow this JVM argument `-Dmidpoint.printSensitiveValues` must be added to the command line,
 value is not required and is ignored.
 This may require modifying `JAVA_OPTS` environment variable or otherwise changing `midpoint.sh` if
 starting scripts are used.