RHIDP-12524: Platform engineer define, name, and view aggregated KPIs for homepage

assemblies/observability_evaluate-project-health-using-scorecards/assembly-configure-scorecard-cards-on-the-homepage.adoc

@@ -0,0 +1,23 @@
+:_mod-docs-content-type: ASSEMBLY
+ifdef::context[:parent-context: {context}]
+
+[id="configure-scorecard-cards-on-the-homepage_{context}"]
+= Configure scorecard cards on the homepage
+
+:context: configure-scorecard-cards-on-the-homepage
+
+[role="_abstract"]
+Scorecard visualization cards on the {product} homepage display aggregated metrics to give engineering managers and platform teams immediate visibility into portfolio health trends.
+
+include::../modules/observability_evaluate-project-health-using-scorecards/proc-configure-a-default-scorecard-aggregation-card.adoc[leveloffset=+1]
+
+include::../modules/observability_evaluate-project-health-using-scorecards/proc-configure-an-aggregation-card-with-a-status-grouped-tracking-type.adoc[leveloffset=+1]
+
+include::../modules/observability_evaluate-project-health-using-scorecards/proc-configure-an-aggregation-card-with-an-average-tracking-type.adoc[leveloffset=+1]
+
+include::../modules/observability_evaluate-project-health-using-scorecards/proc-configure-portfolio-health-on-a-customizable-home-page.adoc[leveloffset=+1]
+
+include::../modules/observability_evaluate-project-health-using-scorecards/proc-configure-portfolio-health-on-a-read-only-home-page.adoc[leveloffset=+1]
+
+ifdef::parent-context[:context: {parent-context}]
+ifndef::parent-context[:!context:]

assemblies/observability_evaluate-project-health-using-scorecards/assembly-monitor-collective-health-across-components.adoc

@@ -4,16 +4,17 @@ ifdef::context[:parent-context: {context}]
 [id="monitor-collective-health-across-components_{context}"]
 = Monitor collective health across components
 
-
 :context: monitor-collective-health-across-components
 [role="_abstract"]
 As an administrator, you can use the Scorecard plugin to view the collective technical health across multiple owned applications or components. This consolidated view helps you identify high-level health trends and risks across complex projects.
 
 include::../modules/observability_evaluate-project-health-using-scorecards/con-monitor-portfolio-health-with-aggregated-kpis.adoc[leveloffset=+1]
 
-include::../modules/observability_evaluate-project-health-using-scorecards/proc-configure-portfolio-health-on-a-customizable-home-page.adoc[leveloffset=+1]
+include::../modules/observability_evaluate-project-health-using-scorecards/con-aggregated-kpis-in-the-scorecard.adoc[leveloffset=+1]
+
+include::../modules/observability_evaluate-project-health-using-scorecards/proc-configure-aggregated-kpis-for-the-scorecard.adoc[leveloffset=+1]
 
-include::../modules/observability_evaluate-project-health-using-scorecards/proc-configure-portfolio-health-on-a-read-only-home-page.adoc[leveloffset=+1]
+include::../modules/observability_evaluate-project-health-using-scorecards/proc-view-detailed-metrics-from-aggregated-scorecard-kpis.adoc[leveloffset=+1]
 
 include::../modules/observability_evaluate-project-health-using-scorecards/proc-schedule-metrics-to-avoid-api-limits.adoc[leveloffset=+1]
 
@@ -24,5 +25,10 @@ include::../modules/observability_evaluate-project-health-using-scorecards/ref-e
 include::../modules/observability_evaluate-project-health-using-scorecards/proc-view-aggregated-metrics-for-owned-entities.adoc[leveloffset=+1]
 
 include::../modules/observability_evaluate-project-health-using-scorecards/ref-available-metric-data-for-entities.adoc[leveloffset=+1]
+
+include::../modules/observability_evaluate-project-health-using-scorecards/ref-scorecard-card-configuration-parameters.adoc[leveloffset=+1]
+
+include::../modules/observability_evaluate-project-health-using-scorecards/ref-scorecard-plugin-rest-api-endpoints-and-parameters.adoc[leveloffset=+1]
+
 ifdef::parent-context[:context: {parent-context}]
 ifndef::parent-context[:!context:]

modules/observability_evaluate-project-health-using-scorecards/con-aggregated-kpis-in-the-scorecard.adoc

@@ -0,0 +1,13 @@
+:_mod-docs-content-type: CONCEPT
+
+[id="aggregated-kpis-in-the-scorecard_{context}"]
+= Aggregated KPIs in the scorecard
+
+[role="_abstract"]
+Monitor the technical health and regulatory compliance of your infrastructure by using aggregated Key Performance Indicators (KPIs). These KPIs summarize complex data from multiple entities into a high-level overview, allowing you to identify system risks quickly.
+
+Aggregated KPIs allow engineering and product managers to monitor the collective status of all entities the viewer owns in the Software Catalog. Instead of manually inspecting individual service scorecards, managers can use these metrics to identify broad trends or risks within their portfolio.
+
+Aggregated metrics rely on the `owner` field defined in the Software Catalog entities to determine which data points to include. The scorecard plugin performs scheduled batch processing to calculate these values; therefore, aggregated data is not updated in real-time.
+
+The plugin supports simple aggregation logic, such as summing values (SUM) or calculating averages (AVERAGE) across entities. 

modules/observability_evaluate-project-health-using-scorecards/proc-configure-a-default-scorecard-aggregation-card.adoc

@@ -0,0 +1,42 @@
+:_mod-docs-content-type: PROCEDURE
+
+[id="configure-a-default-scorecard-aggregation-card_{context}"]
+= Configure a default scorecard aggregation card
+
+[role="_abstract"]
+Add a standard scorecard summary card to your homepage using default, out-of-the-box configurations.
+
+.Prerequisites
+
+* The scorecard plugin is installed and configured in your {product} instance.
+
+* You have administrator permissions to update application configuration files.
+
+.Procedure
+. Open your dynamic plugin configuration file.
+
+. Navigate to your scorecard card block under the `home.page/cards` mount point.
+
+. Update the configuration to use the `aggregationId` property with an established system metric name:
++
+[source,yaml]
+----
+- mountPoint: home.page/cards
+  importName: ScorecardHomepageCard
+  config:
+    props:
+      aggregationId: "github.open_prs"
+    layouts:
+      xl: { w: 3, h: 6, x: 3 }
+      lg: { w: 4, h: 6, x: 4 }
+      md: { w: 6, h: 6, x: 6 }
+      sm: { w: 12, h: 6 }
+      xs: { w: 12, h: 6 }
+      xxs: { w: 12, h: 6 }
+----
+
+. Save the modified configuration file and restart your {product} instance.
+
+.Verification
+. Access your {product-short} homepage interface.
+. Verify that the standard scorecard summary card displays with default metrics.

modules/observability_evaluate-project-health-using-scorecards/proc-configure-aggregated-kpis-for-the-scorecard.adoc

@@ -0,0 +1,46 @@
+:_mod-docs-content-type: PROCEDURE
+
+[id="configure-aggregated-kpis-for-the-scorecard_{context}"]
+= Configure aggregated KPIs for the scorecard
+
+[role="_abstract"]
+Define aggregated Key Performance Indicators (KPIs) in your configuration to provide a consolidated view of team or group health. Aggregating KPIs allows you to summarize technical metrics into high-level insights for management and stakeholders.
+
+.Prerequisites
+* The scorecard plugin is installed and configured in your {product} instance.
+* You have identified the `metricId` you wish to aggregate.
+
+.Procedure
+
+. Access your `app-config.yaml` file.
+
+. Navigate to the `scorecard` section and add an `aggregationKPIs` block.
+
+. Update the configuration to create a homepage card that summarizes a specific metric for a team portfolio. The following example adds a Jira open issues card that groups counts by threshold status for the entities that the signed-in user owns:
++
+[source,yaml]
+----
+scorecard:
+  aggregationKPIs:
+    openIssuesKpi:
+      title: 'Jira open issues KPI'
+      description: 'Open issues across entities you own, grouped by status.'
+      type: statusGrouped
+      metricId: jira.open_issues
+----
++
+where:
++
+`scorecard.aggregationKPIs`:: Map of KPI keys to KPI definitions. Each key is an aggregation ID. For example `openIssuesKpi`.
+`title`:: Title shown for the KPI.
+`description`:: Short description of the KPI.
+`type`:: Aggregation strategy. Use `statusGrouped` for counts per threshold status, or `average` for a weighted portfolio score.
+`metricId`:: Metric provider ID. For example `jira.open_issues`, `github.open_prs`.
+
+. Save the configuration and restart your {product} instance.
+
+.Verification
+
+. Navigate to the {product-short} homepage.
+
+. Verify that the new aggregated card is displayed with the defined name and calculated value.

modules/observability_evaluate-project-health-using-scorecards/proc-configure-an-aggregation-card-with-a-status-grouped-tracking-type.adoc

@@ -0,0 +1,52 @@
+:_mod-docs-content-type: PROCEDURE
+
+[id="configure-an-aggregation-card-with-a-status-grouped-tracking-type_{context}"]
+= Configure an aggregation card with a status-grouped tracking type
+
+[role="_abstract"]
+Configure a scorecard aggregation card to count entities based on status thresholds.
+
+.Prerequisites
+
+* The scorecard plugin is installed and configured in your {product} instance.
+
+.Procedure
+. Open your `app-config.yaml` file.
+
+. Navigate to the `scorecard` section and define your backend Key Performance Indicator (KPI) map within an `aggregationKPIs` block, setting the tracking type to `statusGrouped`:
++
+[source,yaml]
+----
+scorecard:
+  aggregationKPIs:
+    team-alpha-bugs:
+      title: "Team Alpha Bug KPI"
+      description: "Portfolio bug counts grouped by status threshold"
+      type: statusGrouped
+      metricId: jira.open_issues
+----
+. Open your dynamic plugin configuration file.
+
+. Reference your custom aggregation ID inside the homepage card properties block under the `home.page/cards` mount point:
++
+[source,yaml]
+----
+- mountPoint: home.page/cards
+  importName: ScorecardHomepageCard
+  config:
+    props:
+      aggregationId: "team-alpha-bugs"
+    layouts:
+      xl: { w: 3, h: 6 }
+      lg: { w: 4, h: 6 }
+      md: { w: 6, h: 6 }
+      sm: { w: 12, h: 6 }
+      xs: { w: 12, h: 6 }
+      xxs: { w: 12, h: 6 }
+----
+
+. Save the modified configuration files and restart your {product} instance.
+
+.Verification
+. Access your {product-short} homepage interface.
+. Verify that the status-grouped scorecard summary card displays with your defined title and calculations.

modules/observability_evaluate-project-health-using-scorecards/proc-configure-an-aggregation-card-with-an-average-tracking-type.adoc

@@ -0,0 +1,84 @@
+:_mod-docs-content-type: PROCEDURE
+[id="configure-an-aggregation-card-with-an-average-tracking-type_{context}"]
+= Configure an aggregation card with an average tracking type
+
+[role="_abstract"]
+Configure a scorecard aggregation card to calculate a single weighted portfolio score across multiple components.
+
+.Prerequisites
+* The scorecard plugin is installed and configured in your Red Hat Developer Hub instance.
+
+.Procedure
+
+. Open your `app-config.yaml` file.
+
+. Navigate to the `scorecard` section and define your backend Key Performance Indicator (KPI) map within an `aggregationKPIs` block, setting the tracking type to `average`.
+
+. Add the required `statusScores` map to bind numeric weights to your status rules:
++
+[source,yaml]
+----
+scorecard:
+  aggregationKPIs:
+    portfolio-average-health:
+      title: "Portfolio Health KPI"
+      description: "Weighted average score across portfolio components"
+      type: average
+      metricId: github.open_prs
+      options:
+        statusScores:
+          success: 100
+          warning: 50
+          error: 0
+----
+
+. Optional: To override the built-in system defaults, add custom threshold parameters using a continuous, gapless number range evaluated on a scale of `0` to `100`:
++
+[source,yaml]
+----
+options:
+  statusScores:
+    success: 100
+    warning: 50
+    error: 0
+  thresholds:
+    rules:
+    - key: success
+      expression: '>=80'
+      color: '#6bb300' 
+    - key: warning
+      expression: '51-80'
+      color: 'rgb(224, 189, 108)'
+    - key: error
+      expression: '<51'
+      color: '#be1ec7' 
+    - key: critical
+      expression: '<10'
+      color: '#ff0000'
+----
+
+. Open your dynamic plugin configuration file.
+
+. Reference your average tracking aggregation ID inside the homepage card properties block under the `home.page/cards` mount point:
++
+[source,yaml]
+----
+- mountPoint: home.page/cards
+  importName: ScorecardHomepageCard
+  config:
+    props:
+      aggregationId: "portfolio-average-health"
+    layouts:
+      xl: { w: 3, h: 6 }
+      lg: { w: 4, h: 6 }
+      md: { w: 6, h: 6 }
+      sm: { w: 12, h: 6 }
+      xs: { w: 12, h: 6 }
+      xxs: { w: 12, h: 6 }
+----
+
+. Save the modified configuration files and restart your {product} instance.
+
+.Verification
+. Access your {product-short} homepage interface.
+. Verify that the weighted average scorecard summary card displays with your custom scores and thresholds.

modules/observability_evaluate-project-health-using-scorecards/proc-view-detailed-metrics-from-aggregated-scorecard-kpis.adoc

@@ -0,0 +1,57 @@
+:_mod-docs-content-type: PROCEDURE
+
+[id="view-detailed-metrics-from-aggregated-scorecard-kpis_{context}"]
+= View detailed metrics from aggregated scorecard KPIs
+
+[role="_abstract"]
+Configure the {product} Scorecard plugin to enable drill-down capabilities. This allows you to investigate the specific catalog entities and metrics that contribute to aggregated KPI scores, helping to identify and troubleshoot failing applications across a portfolio.
+
+.Prerequisites
+
+* You have installed {product}.
+* You have configured at least one Scorecard metric provider, such as GitHub or Jira.
+* You have configured aggregated KPIs.
+
+.Procedure
+
+. Define the metric ID for drill-down in your `app-config.yaml` file. 
++
+Drill-downs are metric-scoped. Even when you click an aggregated KPI, the system requires the underlying `metricId` to query the catalog for related entities.
++
+[source,yaml]
+----
+jira:
+  product: cloud
+  baseUrl: ${JIRA_URL}
+  token: ${JIRA_TOKEN}     
+scorecard:
+  plugins:
+    jira:
+      open_issues:
+        schedule:
+          frequency: { minutes: 5 }
+          timeout: { minutes: 10 }
+          initialDelay: { seconds: 10 }
+----
+
+. Configure Role-Based Access Control (RBAC) permissions for the relevant user roles to enable scorecard access.
+
+.. Open your RBAC policy file, typically `rbac-policy.csv`.
+
+.. Add the following permission to read both scorecard metrics and catalog entities.
++
+[source,csv]
+----
+p, role:default/team_lead, scorecard.metric.read, read, allow
+p, role:default/team_lead, catalog.entity.read, read, allow
+----
+
+.Verification
+
+.. Navigate to the {product} Home Page.
+
+.. Click an aggregated KPI tile, such as *Critical Jira Issues*.
+
+.. Verify that a list of individual catalog entities appears, showing the components contributing to that aggregate score.
++
+If the list does not appear, ensure you are using the latest version of the {product-very-short} plugins.

modules/observability_evaluate-project-health-using-scorecards/ref-scorecard-card-configuration-parameters.adoc

@@ -0,0 +1,29 @@
+:_mod-docs-content-type: REFERENCE
+
+[id="scorecard-card-configuration-parameters_{context}"]
+= Scorecard card configuration parameters
+
+[role="_abstract"]
+Parameters for application settings and dynamic plugin files used to manage homepage visualizations and portfolio data logic.
+
+== Dynamic plugin properties
+[cols="1,3",options="header"]
+|===
+|Property |Description
+|`aggregationId` |The target identifier for the homepage visualization block. Accepts a default system metric name string or a custom KPI key mapped in your core settings.
+|`metricId` |[Deprecated] Legacy identifier for the source metric string. Supported for backwards compatibility but scheduled for removal in a future release. Replace with `aggregationId`.
+|===
+
+== Application configuration properties (`scorecard.aggregationKPIs`)
+[cols="1,3",options="header"]
+|===
+|Property |Description
+|`title` |The primary textual label rendered on the header block of the homepage card.
+|`description` |A brief text string summarizing the target scope of the KPI.
+|`type` |The structural tracking strategy. Specify `statusGrouped` to return independent numerical entity counts per threshold status layer, or specify `average` to calculate a single weighted portfolio score.
+|`metricId` |The unique provider identifier mapping to the individual source plugin collection layer.
+|===
+
+== Options parameters for the `average` tracking type
+`options.statusScores`:: Map of threshold status rule keys (`success`, `warning`, `error`) to numeric weight integers. This parameter is required for the `average` type and must be non-empty; missing or empty maps cause application startup failures.
+`options.thresholds`:: Optional numeric value array tracking custom status levels evaluated against the `averageScore` output value on a scale from 0 to 100 with one decimal place. If omitted, the system falls back to default values: less than 30 indicates an error, 30 to 79 indicates a warning, and 80 or higher indicates a success. Custom configurations must provide full real-line range coverage with no numeric gaps.