RHIDP-12113: Support customization aggregated homepage scorecard card

[imykhno]

Hey, I just made a Pull Request!

This PR lets system administrators customize the title and description shown on aggregated KPI scorecard cards via app-config, so Engineering and Product Managers to provide company-specific information, ensuring metrics are easily understood by end-users.

Behavior

• Default Aggregated KPIs: The title and description are derived from the metric definition, with the aggregation type set to statusGrouped by default. Internationalisation (i18n) still applies if metric.title or metric.description are present in the plugin catalogues.
• Customized aggregated KPIs: The customization of the aggregated KPIs is performed by using app-config.yaml file. Providing title, description, type and metricId is required to customize aggregated KPI

Configuration

Customization is not under per-provider plugin keys. It lives under scorecard.aggregationKPIs. (app-config.yaml). The homepage wires ScorecardHomepageCard (or equivalent) with props.aggregationId matching that key or the metric id for the default case.
Example:

scorecard:
  aggregationKPIs:
    openIssuesKpi:
      title: 'My Jira issues'
      description: 'Custom description for Jira open issues.'
      type: statusGrouped
      metricId: jira.open_issues

API

Responses that include aggregation metadata:

• New endpoint: GET /aggregations/:aggregationId;
• New endpoint: GET /aggregations/:aggregationId/metadata;
• Deprecated endpoint: GET /metrics/:metricId/catalog/aggregations.

New logic implemented for:

• RHIDP-12113

✔️ Checklist

• A changeset describing the change and affected packages. (more info)
• Added or Updated documentation
• Tests for new functionality and regression tests for bug fixes
• Screenshots attached (for UI changes)

How to test

1. Aggregated KPI (without changing)

The implemented logic supports the deprecated metricId provided in mountPoints. While this logic is currently maintained to allow users to have aggregated KPIs without changing their configuration, it is scheduled for removal in a future release.

• Mount a scorecard homepage card with metricId. Expected to use the same config as used before;
• Configure scorecard aggregated KPI at the homepage;
• Confirm the default titles and descriptions displayed as expected;
• Confirm that that translation works as expected (ref for Eng);

Validate error messages:

• Remove access to "Scorecard" using RBAC;
• Confirm the "Missing permission" error presented on the home page.
• Confirm default titles and descriptions match expectations (ref for Eng).

2. Aggregated KPI (without default configurations)

The new logic supports the default configuration for aggregated KPI cards. Each provider has a default card information therefore, using the default setup does not require any configuration in the app-config.yaml file.

• Mount a scorecard homepage card with aggregationId props equal to a metric id and no matching aggregationKPIs row (or use the documented default pattern). Example: aggregationId: 'jira.open_issues'
• Confirm the default titles and descriptions displayed as expected;
• Confirm that that translation works as expected (ref for Eng);

Validate error messages:

• Remove access to "Scorecard" using RBAC;
• Confirm the "Missing permission" error presented on the home page;
• Confirm default titles and descriptions match expectations (ref for Eng).

3. Aggregated KPI (with customized title and description)

• Add a aggregated KPI card configuration in the app-config.yaml under the scorecard.aggregationKPIs. Example:

scorecard:
  aggregationKPIs:
    openPrsKpi:
      type: statusGrouped
      title: GitHub Open PRs KPI
      metricId: github.open_prs
      description: This KPI is provide information about GitHub open PRs grouped by status.
    openIssuesKpi:
      type: statusGrouped
      title: Jira Open Issues KPI
      metricId: jira.open_issues
      description: This KPI is provide information about Jira open issues grouped by status.

• Mount a scorecard homepage card with aggregationId props equal one of the app-config.yaml aggregationKPIs key. Example: aggregationId: 'aggregationKPIs' or aggregationId: 'openIssuesKpi' following the example;
• Confirm the configured title and description appear on the homepage;
• Confirm that translation is not worked for the card title and title .

Validate error messages:

• Remove access to "Scorecard" using RBAC;
• Confirm the "Missing permission" error presented on the home page;
• **Confirm the title and description are not changed **.

4. Test the /metrics/:metricId/catalog/aggregations endpoint

This endpoint is deprecated and scheduled for removal in the next release. However, it remains available for use in the interim.

# Set environment variables for convenience
export METRIC_ID="your-metric-id" # For example: github.open_prs
export BACKSTAGE_URL="http://localhost:7007"
export TOKEN="your-auth-token-here"

Get aggregated metric

# Set environment variables for convenience
curl -X GET "${BACKSTAGE_URL}/api/scorecard/metrics/${METRIC_ID}/catalog/aggregations" \
  -H "Authorization: Bearer ${TOKEN}" | jq

[rhdh-gh-app]

Changed Packages

Package Name	Package Path	Changeset Bump	Current Version
app-legacy	workspaces/scorecard/packages/app-legacy	none	v0.0.0
app	workspaces/scorecard/packages/app	none	v0.0.0
@red-hat-developer-hub/backstage-plugin-scorecard-backend	workspaces/scorecard/plugins/scorecard-backend	patch	v2.4.0
@red-hat-developer-hub/backstage-plugin-scorecard-common	workspaces/scorecard/plugins/scorecard-common	patch	v2.4.0
@red-hat-developer-hub/backstage-plugin-scorecard	workspaces/scorecard/plugins/scorecard	patch	v2.4.0

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
1.0% Duplication on New Code

See analysis details on SonarQube Cloud