RHIDP-9781: Scorecard KPI aggregated value

assemblies/assembly-monitoring-collective-health-across-sub-entities.adoc

@@ -0,0 +1,23 @@
+:_mod-docs-content-type: ASSEMBLY
+:context: monitoring-collective-health-across-sub-entities
+
+[id="{context}"]
+= Monitoring collective health across sub-entities
+
+You can use the {scorecard-plugin} to view the collective health of sub-entities within a parent entity, such as a `System` or `Domain``. This consolidated view helps you identify high-level health trends and risks across complex projects.
+
+.Procedure
+
+To enable aggregation, you must perform the following steps:
+
+. Define relationships: Ensure sub-entities include the partOf relationship in their definition.
+
+. Apply metadata labels: Add specific labels to the entity metadata to help the backend identify sub-entities.
+
+. Enable aggregation: Toggle the aggregation setting in the parent entity view to display the consolidated score.
+
+The Scorecard backend automatically calculates the parent score based on the results of all identified child entities.
+
+include::modules/observe/scorecards/proc-enabling-aggregated-health-views-for-parent-entities.adoc[leveloffset=+1]
+
+include::modules/observe/scorecards/ref-scorecard-aggregation-settings.adoc[leveloffset=+1]

assemblies/assembly-scorecards-rhdh.adoc

@@ -26,4 +26,6 @@ include::modules/observe/scorecards/ref-override-rules-to-configure-entity-speci
 
 include::modules/observe/scorecards/con-best-practices-for-threshold-rules.adoc[leveloffset=+2]
 
-include::modules/observe/scorecards/proc-viewing-scorecards-in-rhdh.adoc[leveloffset=+1]
+include::modules/observe/scorecards/proc-viewing-scorecards-in-rhdh.adoc[leveloffset=+1]
+
+include::assembly-monitoring-collective-health-across-sub-entities.adoc[leveloffset=+1]

modules/observe/scorecards/proc-enabling-aggregated-health-views-for-parent-entities.adoc

@@ -0,0 +1,49 @@
+:_mod-docs-content-type: PROCEDURE
+
+[id="proc-enabling-aggregated-health-views-for-parent-entities_{context}"]
+= Enabling aggregated health views for parent entities
+
+You can configure the Scorecard plugin to aggregate results for parent entities by updating your {product-very-short} configuration.
+
+.Prerequisites
+
+* The Scorecard plugin is installed and configured.
+* You have administrative access to your {product-very-short} `{my-app-config-file}` file.
+
+.Procedure
+
+. Open your {product-very-short} `{my-app-config-file}` file.
+. Navigate to the `scorecard` section under `catalog`.
+. Add the `aggregation` configuration to enable the feature for specific entity kinds:
++
+[source,yaml]
+----
+catalog:
+  providers:
+    scorecard:
+      aggregation:
+        enabled: true
+        kinds:
+          - System
+          - Domain
+----
+. Save the changes to your {product-very-short} `{my-app-config-file}` file.
+. Restart your {product-very-short} instance to apply the configuration.
+. To enable aggregation for a specific entity, you must update the `catalog-info.yaml` of the entity to include the `scorecard.redhat.com/aggregation` annotation:
++
+[source,yaml]
+----
+apiVersion: backstage.io/v1alpha1
+kind: System
+metadata:
+  name: my-system
+  annotations:
+    scorecard.redhat.com/aggregation: 'enabled'
+spec:
+  owner: guest
+----
+
+.Verification
+
+. In the {product-very-short} catalog, select a parent entity that you configured.
+. Confirm that the *Scorecard* tab displays aggregated results from all child components.

modules/observe/scorecards/ref-scorecard-aggregation-settings.adoc

@@ -0,0 +1,14 @@
+:_mod-docs-content-type: REFERENCE
+
+[id="ref-scorecard-aggregation-settings_{context}"]
+= Scorecard aggregation settings
+
+The following table describes the configuration parameters for entity aggregation in your {product-very-short} `{my-app-config-file}` file.
+
+[cols="25%,15%,60%",options="header"]
+|===
+| Parameter | Type | Description
+| `enabled` | Boolean | Determines if the aggregation feature is active. Default is `false`.
+| `kinds` | Array | Lists the entity kinds, such as `System` or `Domain`, that support aggregated scorecards.
+| `strategy` | String | Specifies the method used to calculate the aggregate score, such as `average` or `lowest`.
+|===