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

docs/misc/reports/configuration/index.adoc

@@ -6,7 +6,9 @@ doc-type: config
 :page-toc: top
 :toclevels: 3
 :page-upkeep-status: green
-:page-upkeep-note: Rewrite, remove mentions of Jasper, explain the basics
+:page-keywords: [ 'report', 'reports', 'reporting' ]
+:search-alias: "report configuration"
+
 
 MidPoint reports can be configured based on the following midPoint concepts:
 
@@ -111,19 +113,26 @@ Naturally you can use them as a basis for your custom reports.
 
 You can create and configure reports also with the use of the xref:/midpoint/reference/interfaces/rest/endpoints/reports.adoc[REST API].
 
-== Tasks for Reports
+== Generate The Report
+
+The actual report (i.e. report file) has to be generated.
+This is done usually by clicking the "run" ("Save and run" or "Run original report") button from the report definition.
+This will execute a special task object which generated the actual report.
+After the "run" button is clicked you can access the task either directly through the "notification" prompt which will appear at the header of the page ("show task" button).
+Or you can access the report through the left vertical menu "Server tasks" > "Report tasks" button.
+Here your task will be present.
+
+The actual report file can be downloaded when the task successfully finished, for this the task GUI contains the "Download report" button.
 
-A report is created by being generated via a task.
-The task for generating a report is executed asynchronously when the "run" button is clicked in the report definition.
 
 There are multiple ways how tasks are build when executed from a report definition, for more information on this and also information how you can distribute the workload of the task to multiple nodes see xref:../configuration/report-task-definition.adoc[this] page
 
-== Import Behaviour 'Import report'
+== Import Behaviour 'Import From Report'
 
 As mentioned above, the report functionality is also capable of using exported reports or custom csv files to create or update objects.
 We call this "Import" or "Reverse" reports, for more information regarding them please see the following page:
 
-xref:../configuration/report-task-definition.adoc[Import Report]
+xref:../configuration/report-task-definition.adoc[Import From Report]
 
 == Multithreading and Bucketing
 

docs/misc/reports/configuration/legacy/index.adoc

@@ -0,0 +1,21 @@
+= Legacy Report Configuration References
+:page-nav-title: Legacy Report Configuration References
+:page-display-order: 100
+:page-toc: top
+:search-alias: "report examples"
+
+== Description
+This section contains some configuration references for older versions in midPoint.
+Please have a look at the "child" pages.
+
+++++
+{% children %}
+++++
+
+== See Also
+
+- xref:/midpoint/reference/misc/reports/configuration/[Report Configuration]
+- xref:/midpoint/reference/misc/reports/configuration/collection-report.adoc[Collection Based Reports]
+- xref:/midpoint/reference/misc/reports/configuration/dashboard-report.adoc[Dashboard Based Reports]
+- xref:/midpoint/reference/misc/reports/configuration/report-security.adoc[Report Security]
+- xref:/midpoint/reference/misc/reports/configuration/report-task-definition.adoc[Report Task Definition]

docs/misc/reports/configuration/report-task-definition.adoc

@@ -41,7 +41,7 @@ The reports can be either "Export" reports or "Import" reports.
     </activity>
 ----
 
-=== Import Report
+=== Import From Report
 
 The second kind of reports are the *"Import"* reports, these work the other way around.
 A CSV is uploaded into midPoint in a similar format as a report, based on this midPoint will create or update objects.

docs/misc/reports/create-report-guide/advanced/index.adoc

@@ -0,0 +1,137 @@
+= Create Report Guide
+:page-since: "4.4"
+
+This guide describe how to create report in GUI. We chose the example report of accounts with resource as parameter and with columns which shows some attributes from owner, to demonstrate all the functionality.
+
+In first step we click on 'Reports' in left menu and next click on 'All Reports' in submenu. In footer of showed report table we click on new report button.
+
+image::create-report-0.png[]
+
+We want to create Collection report, so we select 'Collection report' in showed popup.
+
+image::create-report-1.png[]
+
+Now we see page for editing/creating report. We can fill basic properties, we need fill only name.
+
+image::create-report-2.png[]
+
+Next we can define type of exported file on tab 'Export'. Collection report have default CSV format, so we don't need fill it.
+
+Basic configuration of report define engine, so we open 'Engine' tab. We can see Basic Tab for report engine. We don't need fill basic properties of collection report engine.
+
+image::create-report-3.png[]
+
+As first we open 'Collection' tab, where we define base collection and filter for shadows. At first we select object collection 'All shadows' as base collection. We want to use resource as parameter, so we have to use it in filter.
+
+.Filter
+[source,xml]
+----
+<filter xmlns="http://midpoint.evolveum.com/xml/ns/public/common/common-3"
+        xmlns:q="http://prism.evolveum.com/xml/ns/public/query-3">
+    <q:ref>
+        <q:path>resourceRef</q:path>
+        <expression>
+            <queryInterpretationOfNoValue>filterAll</queryInterpretationOfNoValue>
+            <script>
+                <objectVariableMode>prismReference</objectVariableMode>
+                <code>
+                    import com.evolveum.midpoint.xml.ns._public.common.common_3.ObjectReferenceType;
+
+                    if (!resource) {
+                        return null;
+                    }
+
+                    ObjectReferenceType ort = new ObjectReferenceType();
+                    ort.setOid(resource.getOid());
+                    ort.setRelation(resource.getRelation());
+                    ort.setType(resource.getTargetType());
+                    return ort;
+                </code>
+            </script>
+        </expression>
+    </q:ref>
+</filter>
+----
+
+image::create-report-4.png[]
+
+As next, we define parameter, so we open tab 'Parameter' and add new value to table.
+
+image::create-report-5.png[]
+
+We fill fileds for name with "resource", for type with "ObjectReferenceType" and for label with "Resource". Now we can edit row by edit button in last row. In panel with details of parameter select "Resource" in dropdown of field for 'Target type'.
+
+image::create-report-6.png[]
+
+As next we need define view, so we click on tab 'View' and select type 'Shadow'.
+
+image::create-report-7.png[]
+
+In next step we add new columns for shadow attributes name, kind, intent and one column for demonstration of custom column.
+Creation of columns for shadows attributes is easy. We add three new column and fill fields name, path. When we want some specific label, we can fill it.
+
+image::create-report-8.png[]
+
+We add one more new column and fill fields for name with "customColumn" and label with "Intent and Kind". Now we click on edit button in last column of row. We scroll down to 'Export' container and fill attribute expression with next code:
+
+.Expression of custom column
+[source,xml]
+----
+<script>
+    <code>
+      "Intent: " + object.getIntent() + ", Kind: " + object.getKind()
+   </code>
+</script>
+----
+
+image::create-report-9.png[]
+
+Now we can show preview of actual report. We can show preview in bottom of the screen or in popup, we chose popup. For showing table in bottom of screen click on 'Show report preview' or showing in popup click on 'Show report preview in popup'.
+
+image::create-report-10.png[]
+
+On report preview we can see table with columns and content, which will be shown in exported file.
+
+image::create-report-11.png[]
+
+Now we can add subreport to our report. We close popup and open 'Subreport' tab. We add new column and fill name field with "owner" and field type with "FocusType".
+
+image::create-report-12.png[]
+
+In next step we edit new subreport find field expression and set next snippet of code:
+
+.Expression of subreport
+[source,xml]
+----
+<script>
+    <code>
+      midpoint.searchShadowOwner(object.getOid());
+   </code>
+</script>
+----
+
+image::create-report-13.png[]
+
+Now we can add new column for email of owner. We add new column similar as for custom column and we set next snippet to export expression of column. Also we can fix of order of columns, so we edit every column and fill field for 'Previous column' by name of column which we want see before it.
+
+.Expression of owner email column
+[source,xml]
+----
+<script>
+    <code>
+      if (!owner) {
+        return null;
+      }
+      return owner.getEmailAddress();
+   </code>
+</script>
+----
+
+image::create-report-14.png[]
+
+After we added new column, we can show again report preview in popup. We can see new column with email address from owner, which we got from subreports.
+
+image::create-report-15.png[]
+
+To end we can save and run report and open task. When task will finish, we can download exported file.
+

docs/misc/reports/create-report-guide/index.adoc

@@ -1,137 +1,58 @@
 = Create Report Guide
-:page-since: "4.4"
 
-This guide describe how to create report in GUI. We chose the example report of accounts with resource as parameter and with columns which shows some attributes from owner, to demonstrate all the functionality.
+:page-upkeep-status: green
+:page-keywords: [ 'report', 'create', 'reporting' ]
+:search-alias: "create report"
 
-In first step we click on 'Reports' in left menu and next click on 'All Reports' in submenu. In footer of showed report table we click on new report button.
+== Create A Basic Report
 
-image::create-report-0.png[]
+There is a quick and easy way how to generate a report form an object list.
+This is an example how you can do it.
 
-We want to create Collection report, so we select 'Collection report' in showed popup.
+Let's visit a list of users:
 
-image::create-report-1.png[]
+* go to *Users >All Users*
+* scroll to the *bottom of the screen*
+* click *Create report* (‘pie chart’ button)
 
-Now we see page for editing/creating report. We can fill basic properties, we need fill only name.
+image::users-all.png[]
 
-image::create-report-2.png[]
+The screen represents a *“new” Collection report*. There are a couple of parameters we have to *input*
+here
 
-Next we can define type of exported file on tab 'Export'. Collection report have default CSV format, so we don't need fill it.
+* type in the Name: *All users report*
+* click *Save and run*
 
-Basic configuration of report define engine, so we open 'Engine' tab. We can see Basic Tab for report engine. We don't need fill basic properties of collection report engine.
+image::new-collection-report.png[]
 
-image::create-report-3.png[]
+After success the top screen should have a “blue” banner stating that there is a task on the
+background.
 
-As first we open 'Collection' tab, where we define base collection and filter for shadows. At first we select object collection 'All shadows' as base collection. We want to use resource as parameter, so we have to use it in filter.
+* click *show task* on it
 
-.Filter
-[source,xml]
-----
-<filter xmlns="http://midpoint.evolveum.com/xml/ns/public/common/common-3"
-        xmlns:q="http://prism.evolveum.com/xml/ns/public/query-3">
-    <q:ref>
-        <q:path>resourceRef</q:path>
-        <expression>
-            <queryInterpretationOfNoValue>filterAll</queryInterpretationOfNoValue>
-            <script>
-                <objectVariableMode>prismReference</objectVariableMode>
-                <code>
-                    import com.evolveum.midpoint.xml.ns._public.common.common_3.ObjectReferenceType;
+image::show-tasks.png[]
 
-                    if (!resource) {
-                        return null;
-                    }
+* in the action button container on the top of the page click on the button *Download report*
+* you should have a csv with *all the users in midPoint.*
 
-                    ObjectReferenceType ort = new ObjectReferenceType();
-                    ort.setOid(resource.getOid());
-                    ort.setRelation(resource.getRelation());
-                    ort.setType(resource.getTargetType());
-                    return ort;
-                </code>
-            </script>
-        </expression>
-    </q:ref>
-</filter>
-----
+image::export-report.png[]
 
-image::create-report-4.png[]
 
-As next, we define parameter, so we open tab 'Parameter' and add new value to table.
+== Intermediate Report Customization
 
-image::create-report-5.png[]
+If you want an *example with more customization* please see the xref:/midpoint/reference/misc/reports/create-report-guide/intermediate[intermediate use-case]
 
-We fill fileds for name with "resource", for type with "ObjectReferenceType" and for label with "Resource". Now we can edit row by edit button in last row. In panel with details of parameter select "Resource" in dropdown of field for 'Target type'.
+== Advanced Reporting Use-Case
 
-image::create-report-6.png[]
+In this next topic we look at an advanced reporting set-up.
+In the following article we have described a *custom report* created via the GUI where we fine tune the reported collection and use some *advanced configuration parameters*:
+Some customization via scripting is involved as well.
 
-As next we need define view, so we click on tab 'View' and select type 'Shadow'.
+xref:/midpoint/reference/misc/reports/create-report-guide/advanced[advanced use-case]
 
-image::create-report-7.png[]
-
-In next step we add new columns for shadow attributes name, kind, intent and one column for demonstration of custom column.
-Creation of columns for shadows attributes is easy. We add three new column and fill fields name, path. When we want some specific label, we can fill it.
-
-image::create-report-8.png[]
-
-We add one more new column and fill fields for name with "customColumn" and label with "Intent and Kind". Now we click on edit button in last column of row. We scroll down to 'Export' container and fill attribute expression with next code:
-
-.Expression of custom column
-[source,xml]
-----
-<script>
-    <code>
-      "Intent: " + object.getIntent() + ", Kind: " + object.getKind()
-   </code>
-</script>
-----
-
-image::create-report-9.png[]
-
-Now we can show preview of actual report. We can show preview in bottom of the screen or in popup, we chose popup. For showing table in bottom of screen click on 'Show report preview' or showing in popup click on 'Show report preview in popup'.
-
-image::create-report-10.png[]
-
-On report preview we can see table with columns and content, which will be shown in exported file.
-
-image::create-report-11.png[]
-
-Now we can add subreport to our report. We close popup and open 'Subreport' tab. We add new column and fill name field with "owner" and field type with "FocusType".
-
-image::create-report-12.png[]
-
-In next step we edit new subreport find field expression and set next snippet of code:
-
-.Expression of subreport
-[source,xml]
-----
-<script>
-    <code>
-      midpoint.searchShadowOwner(object.getOid());
-   </code>
-</script>
-----
-
-image::create-report-13.png[]
-
-Now we can add new column for email of owner. We add new column similar as for custom column and we set next snippet to export expression of column. Also we can fix of order of columns, so we edit every column and fill field for 'Previous column' by name of column which we want see before it.
-
-.Expression of owner email column
-[source,xml]
-----
-<script>
-    <code>
-      if (!owner) {
-        return null;
-      }
-      return owner.getEmailAddress();
-   </code>
-</script>
-----
-
-image::create-report-14.png[]
-
-After we added new column, we can show again report preview in popup. We can see new column with email address from owner, which we got from subreports.
-
-image::create-report-15.png[]
-
-To end we can save and run report and open task. When task will finish, we can download exported file.
+== See Also
 
+- xref:/midpoint/reference/misc/reports/examples/[Report Examples]
+- xref:/midpoint/reference/misc/reports/configuration/[Report Configuration]
+- xref:/midpoint/reference/misc/reports/configuration/collection-report.adoc[Collection Based Reports]
+- xref:/midpoint/reference/misc/reports/configuration/dashboard-report.adoc[Dashboard Based Reports]