(this page was created automatically. In case of formatting issues, please visit the official Wiki Page)

Karma

(not verified)

Link to Figma: tba

Overview

• The Dynamic SFM Karma Component displays a karma score in a circular gauge.
• It retrieves the score from a configured data source.
• The score is visualized as one of four levels: Poor, Fair, Good, and Excellent.
• It is useful for showing performance metrics, health scores, or quality ratings.
• The visual gauge makes the information engaging and easy to understand.

Specs

Tokens

Structure

• Consists of a circular gauge that displays a karma score with thresholds for Poor, Fair, Good, and Excellent.

(Configured in General Properties)

• displayName – Sets the display name of the component shown in the structure panel. For example, "Customer Satisfaction Score" allows for easy identification of the component's purpose in the component structure.

(Configured in Visibility Properties)

• displayConditions – Defines conditions for displaying the component. This allows the karma component to be shown or hidden based on dynamic conditions, such as user role, application state, or other contextual factors.

(Configured in Datasource)

• getEntityCollectionDataSourceId – Specifies the data source ID for retrieving the karma data. For example, "api/customer-satisfaction" connects the component to an API endpoint that provides the karma score data.

• getEntityCollectionHttpRequestParametersMap – Configures HTTP parameters for fetching karma data. This object maps additional parameters needed for the data request, allowing for dynamic filtering of karma data based on context. For example, {"QUERY": {"customerId": "{{context.customerId}}"}} would filter results for a specific customer.

• statusField – Defines which field in the response contains the karma value. For example, setting this to "satisfactionScore" will use the value from this field to determine which karma level to display.

Thresholds

(Configured in Datasource)

• poorKarmaThreshold – Sets the threshold value that represents a "Poor" karma level. Values equal to or below this threshold will show as Poor. For example, setting this to "20" means scores of 20 or less will display as Poor karma.
• fairKarmaThreshold – Sets the threshold value that represents a "Fair" karma level. Values above poorKarmaThreshold and up to this value will show as Fair. For example, setting this to "50" means scores between 21 and 50 will display as Fair karma.
• goodKarmaThreshold – Sets the threshold value that represents a "Good" karma level. Values above fairKarmaThreshold and up to this value will show as Good. For example, setting this to "70" means scores between 51 and 70 will display as Good karma.
• excellentKarmaThreshold – Sets the threshold value that represents an "Excellent" karma level. Values above goodKarmaThreshold and up to this value will show as Excellent. For example, setting this to "90" means scores between 71 and 90 will display as Excellent karma.

Actions & Variants

(Configured in Events)

• events – Configures the events that the component can trigger and respond to.
• ON_INIT – Triggered when the component is initialized. Can be used to perform setup operations.
• ON_DESTROY – Triggered when the component is removed from the DOM. Useful for cleanup operations.

Authorization

(Configured in Authorization)

• visibilityPolicySetId – Determines the visibility of the component based on specified policy sets. For example, setting to "customerServicePolicySet" restricts the karma display to users with customer service privileges.

Tests

(Configured in Testing Hooks)

• id – Specifies a unique identifier for the component used for programmatic access. For example, "customerSatisfactionKarma" enables targeted manipulation of this specific karma component.
• dataTestId – Sets the testing hook ID for automated testing. For example, setting it to "customer-karma-gauge" allows test scripts to reliably locate this component.
• enableAsHotspot – Enables the karma component as a guided tour hotspot. When enabled, the karma gauge can be highlighted during guided tours to draw user attention to important metrics.
• guidedTourHotSpotTitle – Sets the title for the guided tour hotspot with support for multiple languages. For example, {"en-US": "Customer Satisfaction Score", "de-DE": "Kundenzufriedenheitswert"} provides localized titles when the karma gauge is highlighted during a guided tour.
• guidedTourHotSpotDescription – Sets the description text for the guided tour hotspot with language support. For example, {"en-US": "This gauge shows the overall satisfaction rating from customer feedback", "de-DE": "Diese Anzeige zeigt die Gesamtzufriedenheitsbewertung aus dem Kundenfeedback"} provides detailed explanations during guided tours.

Guidelines

Sizing & Layout

• Keep the authoring environment clear by naming the instance with displayName; this does not affect end-user layout but improves maintainability in the structure panel.

States & Feedback

• The component surfaces state only through the four threshold levels; it does not expose focus/active/disabled tokens. Configure via poorKarmaThreshold, fairKarmaThreshold, goodKarmaThreshold, excellentKarmaThreshold.

Data-Driven / Conditional Behavior

• Point to the numeric (or rank-like) source with statusField; verify it resolves in the fetched payload from getEntityCollectionDataSourceId.
• Keep thresholds strictly increasing and non-overlapping using poorKarmaThreshold < fairKarmaThreshold < goodKarmaThreshold < excellentKarmaThreshold.
• Ensure the realistic range is covered so every value classifies into exactly one band using the four threshold tokens.
• Stabilize what data is shown by filtering at fetch time with getEntityCollectionHttpRequestParametersMap (e.g., current entity), rather than toggling thresholds at runtime.

Visibility & Authorization

• Gate visibility to roles/policies with visibilityPolicySetId when the metric is sensitive.
• Use displayConditions to show/hide the gauge based on state (e.g., data presence) without reconfiguring sources.

Content & Localization

• For onboarding or contextual explanation, enable the gauge as a hotspot via enableAsHotspot and provide localized copy in guidedTourHotSpotTitle and guidedTourHotSpotDescription.
• Use id and dataTestId to reference the instance consistently in docs, telemetry, and automated checks; keep displayName focused on internal clarity for authors.

Dos & Don’ts

Accessibility

• Localize instructional copy used for guided onboarding via guidedTourHotSpotTitle and guidedTourHotSpotDescription.
• Restrict visibility of sensitive data with visibilityPolicySetId.
• Avoid color-only meaning: when spotlighting the gauge, use concise, localized explanatory text configured via the hotspot fields (enableAsHotspot, guidedTourHotSpotTitle, guidedTourHotSpotDescription).
• Show the component only when the underlying value exists using displayConditions, reducing ambiguity for assistive-technology users.
• Keep classification deterministic by maintaining strictly increasing thresholds using poorKarmaThreshold…excellentKarmaThreshold.