SfSkills Domains Docs GitHub

Home / architect / embedded-analytics-architecture

embedded-analytics-architecture

Use this skill to architect CRM Analytics dashboard embedding in Lightning pages, Experience Cloud, or Visualforce — covering dashboard context strategy, filter/state management, cross-dashboard context propagation, performance optimization, and LWC vs Aura component selection.

Open the skill folder on GitHub

Embedded Analytics Architecture

This skill activates when an architect needs to design the strategy for embedding CRM Analytics dashboards in Lightning Experience, Experience Cloud, or Visualforce — including dashboard context wiring, filter state management, cross-component context propagation, and performance optimization. It produces architecture decisions and configuration specs that developers use to implement embedded analytics correctly.

Before Starting

Gather this context before working on anything in this domain:

Core Concepts

LWC vs Aura Component Selection

Two component options for embedding CRM Analytics dashboards:

LWC wave-wave-dashboard (recommended for Lightning Experience):

Aura wave:waveDashboard (legacy, Visualforce pages only):

Mixing these up is the most common embedded analytics mistake. Using the filter attribute against the LWC component silently has no effect; the state attribute must be used.

Dashboard State and Filter Architecture

The state attribute in the LWC component is a JSON object matching the Filter and Selection Syntax spec:

{
  "filters": [
    {
      "field": "Opportunity.OwnerId",
      "operator": "in",
      "value": ["005xxxxxxxxxxxx"]
    }
  ]
}

State management patterns:

dashboardDevName Runtime Resolution

Hard-coding dashboardDevName causes failures when:

Architecture pattern: store dashboard dev names in a Custom Setting or Custom Metadata Type; retrieve them in Apex and pass to the embedding component. Never hard-code in Lightning component markup.

Common Patterns

Pattern: Record-Context Embedded Dashboard

When to use: When a dashboard on a Lightning record page should automatically filter to the current record's data (e.g., Account dashboard showing that account's opportunities).

How it works:

  1. Use LWC wave-wave-dashboard with record-id="{recordId}" binding
  2. In the dashboard, create a binding that uses the record ID as a filter parameter
  3. Test that the record-id value flows through to the dashboard binding correctly
  4. Do NOT hard-code the dashboard ID — use dashboardDevName resolved from metadata

Pattern: Cross-Dashboard Context Propagation

When to use: When a selection in one embedded dashboard should update the view in an adjacent embedded dashboard on the same page.

How it works:

  1. Add a selection event listener on Dashboard A's LWC component wrapper
  2. Catch the selection event in the parent Lightning Web Component
  3. Build the updated state JSON from the selection value
  4. Call setState() on Dashboard B's LWC component reference to update its filters without full re-render

Decision Guidance

SituationRecommended ApproachReason
Lightning record page embeddingLWC wave-wave-dashboard, record-id attributeNative record context; best performance
Visualforce embeddingAura wave:waveDashboardLWC wave-wave-dashboard not available in Visualforce
Multiple dashboards on one page sharing contextJavaScript getState/setState cross-componentAvoids full re-render; maintains filter state across dashboards
Dashboard dev name varies by environmentStore in Custom Metadata, resolve at runtimeHard-coded dev names break on rename or cross-env promotion
Experience Cloud guest user access to analyticsConfirm Guest User profile analytics permissionGuest users require explicit analytics permission and dashboard sharing
Filtering based on current user attributes$User.Id or $UserAttribute binding in dashboardDo not pass user attributes via URL parameters — security risk

Step-by-step instructions for an AI agent or practitioner working on this task:

  1. Determine the embedding context (Lightning record page, App page, Experience Cloud, Visualforce) and select the appropriate component (LWC for Lightning/Experience Cloud, Aura for Visualforce).
  2. Confirm the dashboard developer name is not hard-coded — design a runtime resolution mechanism (Custom Metadata or Apex) to retrieve it.
  3. Design the filter/state strategy: identify what record or user context should be passed as dashboard filters; specify the state JSON structure for each filter.
  4. Identify any cross-dashboard context propagation requirements: design the event listener and setState pattern for updating adjacent dashboards on selection events.
  5. Plan the Experience Cloud permission model if applicable: confirm Guest User profile has analytics access and the dashboard is shared to the correct community profile.
  6. Performance planning: specify whether the dashboard should load eagerly or lazily (defer load until user scrolls to the component); identify any heavy datasets that should be pre-filtered before embedding.
  7. Document the architecture decision record: component choice, state management approach, dev name resolution strategy, and permission model.

Review Checklist

Run through these before marking work in this area complete:

Salesforce-Specific Gotchas

Non-obvious platform behaviors that cause real production problems:

  1. Using filter attribute syntax on the LWC component silently has no effect — The filter attribute is a legacy Aura wave:waveDashboard property. Using it on the LWC wave-wave-dashboard component silently does nothing — no error, no filter applied. The correct LWC attribute is state, which takes a JSON object using the Filter and Selection Syntax spec. This is the single most common embedded analytics configuration mistake.
  2. Hard-coded dashboardDevName breaks on rename or cross-env promotion — If a dashboard is renamed in any org, or if the developer name differs between sandbox and production, the embedding component silently shows a "dashboard not found" error or renders nothing. Architecture must include a runtime dev name resolution mechanism.
  3. Dashboard state from getState() may return null after Salesforce maintenance — The Replay ID mechanism for Platform Events (analogous issue exists with dashboard state) can be stale after org maintenance. For embedded dashboards, the state should be treated as ephemeral and the embedding component should initialize state fresh from application context on each page load rather than relying on cached state.

Output Artifacts

ArtifactDescription
Embedded analytics architecture decision recordComponent choice, state management approach, dev name resolution, permission model
Dashboard state JSON schemaFilter and Selection Syntax JSON structure for each embedded dashboard
LWC embedding configuration specAttribute bindings, event listeners, setState call patterns

Package files