RHIDP-12601: Scorecard supports custom key values and colors

assemblies/observability_evaluate-project-health-using-scorecards/assembly-scorecard-metric-thresholds.adoc

@@ -20,5 +20,9 @@ include::../modules/observability_evaluate-project-health-using-scorecards/ref-o
 
 include::../modules/observability_evaluate-project-health-using-scorecards/con-verify-logical-flow-in-scorecard-threshold-rules.adoc[leveloffset=+1]
 
+include::../modules/observability_evaluate-project-health-using-scorecards/proc-configure-custom-severity-levels-and-colors-for-scorecard.adoc[leveloffset=+1]
+
+include::../modules/observability_evaluate-project-health-using-scorecards/ref-scorecard-color-configuration-formats.adoc[leveloffset=+1]
+
 ifdef::parent-context[:context: {parent-context}]
 ifndef::parent-context[:!context:]

modules/observability_evaluate-project-health-using-scorecards/proc-configure-custom-severity-levels-and-colors-for-scorecard.adoc

@@ -0,0 +1,62 @@
+:_mod-docs-content-type: PROCEDURE
+
+[id="configure-custom-severity-levels-and-colors-for-scorecard_{context}"]
+= Configure custom severity levels and colors for Scorecard
+
+[role="_abstract"]
+Customizing severity thresholds and color mappings in your Scorecard configuration allows you to visualize platform metrics using your organization's custom operational terminology.
+
+[NOTE]
+====
+Each custom severity threshold key requires both a corresponding icon configuration value and a color parameter configuration value. Because the portal validates the YAML configuration files during application startup, omitting either property or providing an invalid value causes an initialization failure, and the Scorecard plugin fails to function.
+====
+
+.Prerequisites
+* You have administrative access to the {product} configuration files.
+* You have added a custom application configuration file to your {product} deployment workspace.
+* An existing configuration for the Scorecard backend plugin is deployed with at least one active Scorecard plugin module workspace.
+
+.Procedure
+
+. Open the {product-very-short} `app-config.yaml` file.
+
+. Navigate to the `scorecard.plugins` backend threshold definition block.
+
+. Define your custom severity threshold keys by adding a structured rule entry containing your custom key string, your boundary expression, your preferred color parameter format, and a supported icon string variable.
++
+[source,yaml]
+----
+scorecard:
+  plugins:
+    myDatasource:
+      myMetric:
+        thresholds:
+          rules:
+            - key: ideal
+              expression: '<10'
+              color: '#5CE65C'
+              icon: star
+            - key: warning
+              expression: '10-50'
+              color: 'rgb(233, 213, 2)'
+              icon: monitor
+            - key: critical
+              expression: '>50'
+              color: error.main
+              icon: scorecardErrorStatusIcon
+----
+
+. Save the changes to the configuration file.
+
+. Restart your {product} instance to apply the new threshold rules.
+
+.Verification
+
+* Open the {product} UI, navigate to the Scorecard component, and verify that the custom severity levels display with the colors and icons you specified.
+
+[role="_additional-resources"]
+.Additional resources
+
+* link:https://docs.redhat.com/en/documentation/red_hat_developer_hub/latest/html/administration_guide_for_red_hat_developer_hub/assembly-add-custom-app-file-openshift_admin-rhdh[Adding a custom application configuration file to Red Hat OpenShift Container Platform]
+* link:https://docs.redhat.com/en/documentation/red_hat_developer_hub/latest/html-single/evaluate_project_health_using_scorecards/index#enable-scorecards_set-up-scorecards-to-monitor-your-project-health[Enabling Scorecards]
+* link:https://docs.redhat.com/en/documentation/red_hat_developer_hub/latest/html-single/evaluate_project_health_using_scorecards/index#install-and-configure-scorecards-to-view-metrics_evaluate-project-health-using-scorecards[Installing and configuring Scorecards to view metrics]

modules/observability_evaluate-project-health-using-scorecards/ref-scorecard-color-configuration-formats.adoc

@@ -0,0 +1,55 @@
+:_mod-docs-content-type: REFERENCE
+
+[id="scorecard-color-configuration-formats_{context}"]
+= Scorecard color configuration formats
+
+[role="_abstract"]
+Learn the supported color string formats and syntax rules required to map custom severity threshold keys in the configuration parser.
+
+== Threshold color mapping values
+[cols="1,2",options="header"]
+|===
+|Color format type |Configuration examples
+|Theme palette references
+|`success.main`, `warning.main`, `error.main`
+|HEX hexadecimal codes
+|`'#5CE65C'`, `'#FFA500'`
+|RGB or RGBA functional strings
+|`'rgb(233, 213, 2)'`, `'rgba(255, 0, 0, 0.8)'`
+|===
+
+[NOTE]
+====
+The default threshold rules use the built-in theme palette references: `success.main` for success states, `warning.main` for warning states, and `error.main` for error states. You can use these standard theme indicators for custom severity levels if desired.
+====
+
+[id="scorecard-icon-configuration-formats_{context}"]
+== Supported threshold icon configuration formats
+
+To determine what graphic displays in the metrics matrix block, the Scorecard plugin uses standard frontend mapping components, allowing you to specify icons using any of the following parameters.
+
+[NOTE]
+====
+When using Material Design strings, you must specify icons that are explicitly ingested and bundled inside your Red Hat Developer Hub layout package (such as `star` or `monitor`). Standard upstream values that are not ingested (such as `check`) will not appear in the user interface.
+====
+
+== Threshold icon component options
+[cols="1,2",options="header"]
+|===
+|Icon syntax layout |Value definition format examples
+|Backstage system icons
+|`'kind:component'`, `'kind:api'`
+|Material Design icon strings
+|`'settings'`, `'home'`, `'build'`, `'star'`, `'monitor'`
+|Inline SVG strings
+|Raw xml element blocks (for example, `'<svg>...</svg>'`)
+|External URLs
+|`'https://example.com/icon.png'`, `'/assets/icon.svg'`
+|Data encoded URIs
+|`'data:image/svg+xml;base64,...'`
+|===
+
+[NOTE]
+====
+The standard threshold keys use pre-configured system definitions by default: `scorecardSuccess` for success rule matches, `scorecardWarningStatusIcon` for warning rule matches, and `scorecardErrorStatusIcon` for error rule matches.
+====