Do minor simulation updates

Evolveum · Mar 2, 2023 · 0450351 · 0450351
1 parent 7a27024
commit 0450351
Show file tree

Hide file tree

Showing 5 changed files with 75 additions and 8 deletions.
diff --git a/docs/simulation/reports/index.adoc b/docs/simulation/reports/index.adoc
@@ -35,15 +35,15 @@ Usually contains information about the task that produced the report (if any), i
 (Empty for foreground simulations.)
 | Production configuration
 | #TODO# this will be changed (either true/false or set name)
-2+| The following part of the report is instantiated once per each simulation xref:../results/metrics.adoc[metric] (event mark-based or custom one).
+2+| _The following part of the report is instantiated once per each simulation xref:../results/metrics.adoc[metric] (event mark-based or custom one)._
 | Event mark
 | Event mark corresponding to the metric row. (If applicable.)
 | Custom metric
 | Custom metric identifier corresponding to the metric row. (If applicable.)
 | Aggregation function
 | Aggregation function used for given metric.
 See xref:../results/aggregation-functions.adoc[].
-2+| The following part of the report is instantiated once per each xref:../results/partitions.adoc[metric partition].
+2+| _The following part of the report is instantiated once per each xref:../results/partitions.adoc[metric partition]._
 | Scope: type
 | Type of objects (user, role, org, shadow, ...).
 | Scope: archetype
@@ -67,3 +67,17 @@ The default meaning is "all objects that have metric value greater than zero".)
 | Domain total value
 | Sum of metric values for all objects.
 |===
+
+Report parameters (#planned#):
+
+[%autowidth]
+[%header]
+|===
+| Parameter | Description
+| Result | Specific simulation result we want to report on.
+| Name | Part of simulation result name to match.
+| Task | The task on whose simulation results we want to report on.
+| Started not earlier than | Selects simulation reports started on or after given time instant.
+|===
+
+Note: the above criteria are "and"-ed together.
diff --git a/docs/simulation/running/tasks.adoc b/docs/simulation/running/tasks.adoc
@@ -0,0 +1,42 @@
+= Running Simulation in Tasks
+:page-since: "4.7"
+
+An example of running a simulation task:
+
+.Listing 1. An import task executing in simulation mode, over development configuration, and with creation of a simulation result
+[source,xml]
+----
+<task xmlns="http://midpoint.evolveum.com/xml/ns/public/common/common-3"
+      xmlns:ri="http://midpoint.evolveum.com/xml/ns/public/resource/instance-3"
+      oid="8b169df3-3124-4e36-871f-83bb52acfd7b">
+    <name>Simulated import from HR</name>
+    <executionState>runnable</executionState>
+    <activity>
+        <work>
+            <import>
+                <resourceObjects>
+                    <resourceRef oid="236dd5ca-47df-403c-82e1-9ce2f36be000"/>
+                    <objectclass>ri:AccountObjectClass</objectclass>
+                </resourceObjects>
+            </import>
+        </work>
+        <execution>
+            <mode>preview</mode> <!--1-->
+            <configurationToUse>
+                <set>development</set> <!--2-->
+            </configurationToUse>
+        </execution>
+        <reporting>
+            <simulationResult/> <!--3-->
+        </reporting>
+    </activity>
+</task>
+----
+<1> The value of `preview` means we do not want to execute the actions in this task.
+<2> `development` means we want to use the development configuration in this task.
+<3> The presence of `simulationResult` means we want to create the simulation result object.
+
+For more information, please see
+
+- xref:/midpoint/reference/tasks/activities/execution-mode.adoc[activity execution mode] specification
+- xref:/midpoint/reference/tasks/activities/reporting/simulation-result.adoc[activity simulation result] definition.
diff --git a/docs/tasks/activities/execution-mode.adoc b/docs/tasks/activities/execution-mode.adoc
@@ -28,3 +28,5 @@ The `preview` and `dryRun` execution modes are supported by the following activi
 * synchronization ones: import, live synchronization, reconciliation,
 * recomputation activity.
 ====
+
+#TODO new `execution` element#
diff --git a/docs/tasks/activities/reporting/index.adoc b/docs/tasks/activities/reporting/index.adoc
@@ -14,29 +14,34 @@ also do not support these options.
 |===
 | Item | Meaning | Default
 
-| link:logging[`logging`]
+| xref:logging.adoc[`logging`]
 | Controls logging aspects of an activity execution.
 | See the description.
 
-| link:tracing[`tracing`]
+| xref:tracing.adoc[`tracing`]
 | Specifies when and how should be the activity execution traced.
 | No tracing.
 
-| link:profiling[`profiling`]
+| xref:profiling.adoc[`profiling`]
 | Specifies when and how should be the activity execution dynamically profiled.
 This functionality is deprecated. The tracing should be used instead.
 | No profiling.
 
-| link:execution-reports[`executionReports`]
+| xref:execution-reports.adoc[`executionReports`]
 | Configures specific activity execution reports: on buckets, items, and so on.
 | No reports.
 
-| link:item-counting[`itemCounting`]
+| xref:item-counting.adoc[`itemCounting`]
 | How should the activity deal with item counting, i.e. determining "expected progress"
 for a bucket or overall.
 | TODO
 
-| link:state-overview[`stateOverview`]
+| xref:state-overview.adoc[`stateOverview`]
 | Parameters related to the maintenance of activity tree state overview.
 | TODO
+
+| xref:simulation-result.adoc[`simulationResult`]
+| Whether we want to create a simulation result object for this activity run.
+Since 4.7.
+| No.
 |===
diff --git a/docs/tasks/activities/reporting/simulation-result.adoc b/docs/tasks/activities/reporting/simulation-result.adoc
@@ -0,0 +1,4 @@
+= Simulation Result
+:page-since: "4.7"
+
+#TODO#