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

Evolveum · Apr 25, 2024 · c45862c · c45862c
2 parents 2814959 + ff06d5e
commit c45862c
Show file tree

Hide file tree

Showing 13 changed files with 123 additions and 75 deletions.
diff --git a/docs/admin-gui/dashboards/configuration/index.adoc b/docs/admin-gui/dashboards/configuration/index.adoc
@@ -521,10 +521,13 @@ And next we create dashboard with one widget for enabled users.
 ----
 ====
 
-Don't forget to add the new dashboard to admin gui in system configuration. After accessing the new dashboard in GUI you can see our new widget.
+Don't forget to add the new dashboard to admin gui in system configuration.
+
+After accessing the new dashboard in GUI you can see our new widget.
 
 image::enabled-users.png[]
 
+[#_asynchronous_widget]
 == Asynchronous widget
 
 To configure an asynchronous widget we have to use the `displaySourceType` attribute in the widget configuration and set it as `widgetData`.
@@ -536,95 +539,42 @@ For this we use a dashboard report with the element `storeExportedWidgetData`.
 For example, we will use the same case as in the previous example for enabled users.
 We create the same object collection.
 
-[%collapsible]
+//TODO check after sampleRef is fully in prod
 .*Example Object Collection*
+[%collapsible]
 ====
-[source,xml]
-----
-<objectCollection oid="00000000-0000-0000-0001-000000147896">
-   <name>All enabled users</name>
-    <type>UserType</type>
-    <filter>
-        <equal>
-            <path>activation/effectiveStatus</path>
-            <value>enabled</value>
-        </equal>
-    </filter>
-</objectCollection>
-----
+link::https://github.com/Evolveum/midpoint-samples/blob/master/samples/dashboard/howto/collection-enabled-users.xml [Git]
+
+sampleRef::samples/dashboard/howto/collection-enabled-users.xml[]
 ====
 
 Next, we have to create a dashboard. We also need to add the attribute `displaySourceType` with value `widgetData`.
 
+//TODO check after sampleRef is fully in prod
 [%collapsible]
 .*Example Dashboard Configuration*
 ====
-[source,xml]
-----
-<dashboard oid="f89709f9-7313-494f-a600-69ea75d95106">
-    <name>Example one widget for enabled users</name>
-    <display>
-        <label>Enabled users</label>
-    </display>
-    <widget>
-        <identifier>enabled-users</identifier>
-        <display>
-            <label>Enabled users</label>
-            <color>#00a65a</color>
-            <icon>
-                <cssClass>fa fa-user</cssClass>
-            </icon>
-        </display>
-        <data>
-            <sourceType>objectCollection</sourceType>
-            <displaySourceType>widgetData</displaySourceType>
-            <collection>
-                <collectionRef oid="00000000-0000-0000-0001-000000147896" type="ObjectCollectionType"/>
-            </collection>
-        </data>
-        <presentation>
-            <dataField>
-                <fieldType>value</fieldType>
-                <expression>
-                    <proportional>
-                        <style>value-only</style>
-                    </proportional>
-                </expression>
-            </dataField>
-            <dataField>
-                <fieldType>unit</fieldType>
-                <expression>
-                    <value>enabled</value>
-                </expression>
-            </dataField>
-        </presentation>
-    </widget>
-</dashboard>
-----
+link::https://github.com/Evolveum/midpoint-samples/blob/master/samples/dashboard/dashboard-asynchronous-widget.xml [Git]
+
+sampleRef::samples/dashboard/dashboard-asynchronous-widget.xml[]
 ====
 
 Finally, we create a report for dashboard.
 
+//TODO check after sampleRef is fully in prod
 [%collapsible]
 .*Example Report Configuration*
 ====
-[source,xml]
-----
-<report>
-    <name>Enabled users report</name>
-    <assignment>
-        <targetRef oid="00000000-0000-0000-0000-000000000170" type="ArchetypeType"/>
-    </assignment>
-    <dashboard>
-        <dashboardRef oid="f89709f9-7313-494f-a600-69ea75d95106" type="DashboardType"/>
-        <showOnlyWidgetsTable>true</showOnlyWidgetsTable>
-        <storeExportedWidgetData>onlyWidget</storeExportedWidgetData>
-    </dashboard>
-</report>
-----
+link::https://github.com/Evolveum/midpoint-samples/blob/master/samples/dashboard/report-asynchronous-widget.xml [Git]
+
+sampleRef::samples/dashboard/report-asynchronous-widget.xml[]
 ====
 
-Now we can run the report and midPoint processes the source data for the dashboard. The resulting data is written to the widget in the dashboard.
+Now we can run the report and midPoint processes the source data for the dashboard.
+The resulting data is written to the widget in the dashboard.
+
+include::../raw/file-format.adoc[]
+
 Next time you open the widget in the GUI, midPoint doesn't need to process the source data, it shows the saved data present in the object xml.
 
 image::enabled-users.png[]

diff --git a/docs/admin-gui/dashboards/index.adoc b/docs/admin-gui/dashboards/index.adoc
@@ -10,9 +10,14 @@ doc-type: intro
 :page-wiki-metadata-modify-user: semancik
 :page-wiki-metadata-modify-date: 2019-02-01T13:16:14.087+01:00
 :page-nav-title: Dashboards
+:page-keywords: [ 'dashboards', 'dashboard' ]
+:search-alias: "dashboards"
 :page-since: "4.0"
 :page-upkeep-status: orange
-:page-upkeep-note: This was a "planned feature" test. I have quicly edited it to be a in present tense. But perhaps more edits are needed.
+:page-upkeep-note: This was a "planned feature" test. I have quickly edited it to be a in present tense. But perhaps more edits are needed.
+
+
+== Description
 
 From the early days of midPoint there were two hardcoded dashboards: end-user home dashboard and administration dashboard.
 That was fine while midPoint was a simple IDM system.
@@ -28,7 +33,7 @@ And then data protection officer will need yet another way to present the data.
 Therefore, we need something that will be flexible and customizable.
 Such as customizable dashboards.
 
-In midPoint universe, dashboards are first-class citizens.
+In the midPoint universe, dashboards are first-class citizens.
 Each deployment can have as many dashboards as needed, and they can contain custom "widgets" used to present interesting pieces of information.
 Simple widgets can present data from xref:/midpoint/reference/admin-gui/collections-views/[object collections], such as number of active employees, number of failed resources, suspended tasks and so.
 That is an elegant way to create _status dashboards_ showing status of important system components.

diff --git a/docs/admin-gui/dashboards/raw/file-format.adoc b/docs/admin-gui/dashboards/raw/file-format.adoc
@@ -0,0 +1,10 @@
+:page-visibility: hidden
+:page-upkeep-status: green
+
+[NOTE]
+====
+It makes sense to run the task for an asynchronous widget as a reoccurring task.
+Yet there is no way how to pre-configure the task before you actually "run" the report.
+Because of this, the only way is to run the report and afterwards modify the task, so it runs periodically.
+There is a work package regarding this at bug:MID-9646[]
+====
diff --git a/docs/admin-gui/dashboards/raw/index.adoc b/docs/admin-gui/dashboards/raw/index.adoc
@@ -0,0 +1,2 @@
+:page-visibility: hidden
+:page-upkeep-status: green
diff --git a/docs/misc/reports/configuration/collection-report.adoc b/docs/misc/reports/configuration/collection-report.adoc
@@ -189,6 +189,12 @@ image::collection-parameters.png[]
 sampleRef::samples/reports/report-user-list-advanced.xml[]
 ====
 
+When you click on the "Run original report" button, a report preview will be generated in a modal window.
+In this window you can click the "Run report" button.
+This will create a task which will generate the actual report output.
+Bear in mind that even the report preview can take some time to generate based on the complexity and size of data.
+We have a work package tracking this bug:MID-9648[]
+
 image::collection-parameter-example.png[75%]
 
 We can use following attributes for parameter:

diff --git a/docs/misc/reports/configuration/dashboard-report.adoc b/docs/misc/reports/configuration/dashboard-report.adoc
@@ -145,6 +145,19 @@ Configuration of Dashboard report contains attribute _storeExportedWidgetData_,
 
 |===
 
+//TODO check after sampleRef is fully in prod
+[%collapsible]
+.*Example Report Configuration*
+====
+link::https://github.com/Evolveum/midpoint-samples/blob/master/samples/dashboard/report-asynchronous-widget.xml [Git]
+
+sampleRef::samples/dashboard/report-asynchronous-widget.xml[]
+====
+
+include::../../../admin-gui/dashboards/raw/file-format.adoc[]
+
+Please also have a look at the full configuration documentation of asynchronous xref:/midpoint/reference/admin-gui/dashboards/configuration/#_asynchronous_widget[dashboards].
+
 === Example of Generated Report
 
 On the screenshot, we can see an example of a generated report of a Dashboard report in the HTML format.

diff --git a/docs/misc/reports/examples/audit-report-with-changed-attributes.adoc b/docs/misc/reports/examples/audit-report-with-changed-attributes.adoc
@@ -18,9 +18,12 @@ We need to create a report for audit events of modifications with a column for c
 
 Configuration for this use case consists only from the report itself, because we use an object collection from the initial objects.
 
+//TODO check after sampleRef is fully in prod
 .*Example Report Configuration*
 [%collapsible]
 ====
+link::https://github.com/Evolveum/midpoint-samples/blob/master/samples/reports/audit-report-changed-attrs.xml[Git]
+
 sampleRef::samples/reports/audit-report-changed-attrs.xml[]
 ====
 

diff --git a/...ports/examples/comparing-attributes-of-shadow-and-attributes-of-user-in-mp.adoc b/...ports/examples/comparing-attributes-of-shadow-and-attributes-of-user-in-mp.adoc
@@ -19,27 +19,39 @@ We need report users with mismatched attributes, so we have to compare attribute
 
 We need import object collection and report.
 
+//TODO check after sampleRef is fully in prod
 .*Example Resource Configuration*
 [%collapsible]
 ====
+link::https://github.com/Evolveum/midpoint-samples/blob/master/samples/resources/csv/resource-csv-username.xml[Git]
+
 sampleRef::samples/resources/csv/resource-csv-username.xml[]
 ====
 
+//TODO check after sampleRef is fully in prod
 .*Example CSV Source File*
 [%collapsible]
 ====
+link::https://github.com/Evolveum/midpoint-samples/blob/master/samples/resources/csv/midpoint-username.csv[Git]
+
 sampleRef::samples/resources/csv/midpoint-username.csv[]
 ====
 
+//TODO check after sampleRef is fully in prod
 .*Example Object Collection*
 [%collapsible]
 ====
+link::https://github.com/Evolveum/midpoint-samples/blob/master/samples/objectCollection/resource-account-shadows.xml[Git]
+
 sampleRef::samples/objectCollection/resource-account-shadows.xml[]
 ====
 
+//TODO check after sampleRef is fully in prod
 .*Example Report Configuration*
 [%collapsible]
 ====
+link::https://github.com/Evolveum/midpoint-samples/blob/master/samples/reports/comparing-attributes.xml[Git]
+
 sampleRef::samples/reports/comparing-attributes.xml[]
 ====
 

diff --git a/docs/misc/reports/examples/example-policysituation/index.adoc b/docs/misc/reports/examples/example-policysituation/index.adoc
@@ -19,38 +19,49 @@ The Administrator needs to display all users which have value of description set
 
 At first, we need to configure a policy rule. In this Example we add the following snippet of configuration to our system configuration in Midpoint.
 
+//TODO check after sampleRef is fully in prod
 .*Example System Config configuration*
 [%collapsible]
 ====
+link::https://github.com/Evolveum/midpoint-samples/blob/master/samples/misc/system-policy-rec.xml[Git]
+
 sampleRef::samples/misc/system-policy-rec.xml[]
 ====
 
 Now, we have to recompute all users in order to set our policySituation for them, when they meet the criteria of our filter.
 
 Afterwards We need to configure object collection for users with policySituation.
 
+//TODO check after sampleRef is fully in prod
 .*Example ObjectCollection configuration*
 [%collapsible]
 ====
+link::https://github.com/Evolveum/midpoint-samples/blob/master/samples/objectCollection/users-with-policySituation.xml[Git]
+
 sampleRef::samples/objectCollection/users-with-policySituation.xml[]
 ====
 
 When we have the object collection in place, we want to set up an import Dashboard object with a widget for our object collection.
 
+//TODO check after sampleRef is fully in prod
 .*Example Dashboard configuration*
 [%collapsible]
 ====
+link::https://github.com/Evolveum/midpoint-samples/blob/master/samples/dashboard/users-policy-situation.xml[Git]
+
 sampleRef::samples/dashboard/users-policy-situation.xml[]
 ====
 
 After the successful import of the dashboard object you can see the dashboard in the menu *Dashboards* > *Users created by mP dashboard*.
 
 We want to report it out as a table of users created by Midpoint, for this we can use a dashboard report.
 
-
+//TODO check after sampleRef is fully in prod
 .*Example Dashboard Report Configuration*
 [%collapsible]
 ====
+link::https://github.com/Evolveum/midpoint-samples/blob/master/samples/reports/users-created-policy-dashboard-report.xml[Git]
+
 sampleRef::samples/reports/users-created-policy-dashboard-report.xml[]
 ====
 

diff --git a/docs/misc/reports/examples/example-report-audit-administrativestatus.adoc b/docs/misc/reports/examples/example-report-audit-administrativestatus.adoc
@@ -27,58 +27,79 @@ CREATE INDEX iAuditEventCustSituation
     ON ma_audit_event (custSituation);
 ----
 
+//TODO check after sampleRef is fully in prod
 .*Example Resource Configuration*
 [%collapsible]
 ====
+link::https://github.com/Evolveum/midpoint-samples/blob/master/samples/resources/csv/resource-csv-username.xml[Git]
+
 sampleRef::samples/resources/csv/resource-csv-username.xml[]
 ====
 
+//TODO check after sampleRef is fully in prod
 .*Example CSV Source File*
 [%collapsible]
 ====
+link::https://github.com/Evolveum/midpoint-samples/blob/master/samples/resources/csv/midpoint-username.csv[Git]
+
 sampleRef::samples/resources/csv/midpoint-username.csv[]
 ====
 
 As next adding we're adding next snippet of configuration to config.xml file in Midpoint home directory.
 
+//TODO check after sampleRef is fully in prod
 .*config.xml configuration snippet*
 [%collapsible]
 ====
+link::https://github.com/Evolveum/midpoint-samples/blob/master/samples/misc/config-custom-column.xml[Git]
+
 sampleRef::samples/misc/config-custom-column.xml[]
 ====
 
 After modifying config.xml we have to restart Midpoint. As last part of adding custom column adding next configuration to system configuration.
 
+//TODO check after sampleRef is fully in prod
 .*Snippet of system configuration*
 [%collapsible]
 ====
+link::https://github.com/Evolveum/midpoint-samples/blob/master/samples/misc/system-config-event-rec.xml[Git]
+
 sampleRef::samples/misc/system-config-event-rec.xml[]
 ====
 
  I chose situations are split by '|', but you can use more columns. Now, we need configure object collection for audit records.
 In object collection for audit events we use sql select command.
 
+//TODO check after sampleRef is fully in prod
 .*Object collection*
 [%collapsible]
 ====
+link::https://github.com/Evolveum/midpoint-samples/blob/master/samples/objectCollection/admin-status-midification.xml[Git]
+
 sampleRef::samples/objectCollection/admin-status-midification.xml[]
 ====
 
 When we have object collection, then import Dashboard object with widget for our object collection.
 
+//TODO check after sampleRef is fully in prod
 .*Dashboard*
 [%collapsible]
 ====
+link::https://github.com/Evolveum/midpoint-samples/blob/master/samples/dashboard/change-of-admin-status-custom-column.xml[Git]
+
 sampleRef::samples/dashboard/change-of-admin-status-custom-column.xml[]
 ====
 
 After successful import of dashboard object and reload of page you can see dashboard in menu *Dashboards* > *Changes of administrativeStatus(R1)*.
 
 We want report with table of audit events, so we import dashboard report.
 
+//TODO check after sampleRef is fully in prod
 .*Report*
 [%collapsible]
 ====
+link::https://github.com/Evolveum/midpoint-samples/blob/master/samples/reports/dashboard-report-custom-column.xml[Git]
+
 sampleRef::samples/reports/dashboard-report-custom-column.xml[]
 ====