RHIDP-12524: updated PR after discussion with Patrick, and using claude to run style checks

Author: rh-tokeefe

modules/observability_evaluate-project-health-using-scorecards/proc-configure-aggregated-scorecard-kpis-to-monitor-the-health-of-multiple-applications.adoc

@@ -4,9 +4,7 @@
 = Configure aggregated Scorecard KPIs to monitor the health of multiple applications
 
 [role="_abstract"]
-Configure the {product} Scorecard plugin to enable drill-down capabilities, allowing users to investigate the specific catalog entities and metrics that contribute to aggregated KPI scores.
-
-Monitoring collective health across a portfolio allows team leads and managers to identify trends. By configuring drill-downs, users can quickly analyze which specific applications are failing or require attention.
+Configure drill-downs to quickly identify trends across your application portfolio and analyze which specific applications require attention. Monitoring collective health across a portfolio allows team leads and managers to identify patterns, prioritize issues, and take action on applications that are failing or need intervention.
 
 .Prerequisites
 
@@ -16,22 +14,46 @@ Monitoring collective health across a portfolio allows team leads and managers t
 
 .Procedure
 
-. Define the metric ID for drill-down in your `app-config.yaml` file. Drill-downs are metric-scoped. Even when clicking an aggregated KPI, the system requires the underlying `metricId` to query the catalog for related entities.
+. 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]
 ----
+proxy:
+  '/jira/api':
+    target: ${JIRA_URL}
+    headers:
+      Authorization: ${JIRA_TOKEN}
+      Accept: 'application/json'
+      Content-Type: 'application/json'
+      X-Atlassian-Token: 'nocheck'
+      User-Agent: 'MY-UA-STRING'
+jira:
+  product: cloud
+  baseUrl: ${JIRA_URL}
+  token: ${JIRA_TOKEN}      
 scorecard:
-  kpis:
-    - id: criticalJiraIssuesKpi
-      metricId: jira.critical_issues
-      type: average
+  aggregationKPIs:
+    openIssuesKpi:
+      title: Jira Open Issues KPI
+      type: statusGrouped
+      description: This KPI provides information about Jira open issues grouped by status.
+      metricId: jira.open_issues # must match the `plugins.jira.open_issues` section
+  plugins:
+    jira:
+      open_issues:
+        schedule:
+          frequency: { minutes: 5 }
+          timeout: { minutes: 10 }
+          initialDelay: { seconds: 10 }
 ----
 
-. Assign the required Role-Based Access Control (RBAC) permissions to the relevant user roles.
+. 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 or verify that users have permission to read both scorecard metrics and catalog entities.
+.. Add the following permission to read both scorecard metrics and catalog entities.
 +
 [source,csv]
 ----
@@ -41,10 +63,10 @@ p, role:default/team_lead, catalog.entity, read, allow
 
 .Verification
 
-. Ensure your Scorecard backend supports the `/metrics/:metricId/catalog/aggregations/entities` endpoint by checking that you are using the latest version of the {product-very-short} plugins.
-
-.. Navigate to the {product} Home Page and verify the drill-down action.
+.. 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.