AnalyticsDashboard Metadata Type in SFDX

Architectural Overview#

While the standard Dashboard metadata type handles operational CRM dashboards backed by up to 20 standard Report components, enterprise business intelligence requires multi-dataset faceting, dynamic bindings, and high-volume aggregation. The AnalyticsDashboard metadata type represents these advanced analytics dashboards in Metadata API.

Architecturally, managing AnalyticsDashboard definitions in SFDX allows BI engineers and Salesforce architects to review query logic, widget layouts, and dataset references in Git pull requests before promoting executive dashboards to production.

SFDX Directory & File Suffix#

Key Metadata Fields#

Declarative XML & package.xml Examples#

Sample .analyticsDashboard-meta.xml#

<?xml version="1.0" encoding="UTF-8"?>
<AnalyticsDashboard xmlns="http://soap.sforce.com/2006/04/metadata">
    <application>Executive_Sales_Analytics</application>
    <description>Multi-touch pipeline velocity, quota attainment, and regional YoY bookings analytics dashboard.</description>
    <masterLabel>Executive Revenue Velocity</masterLabel>
</AnalyticsDashboard>

Sample package.xml Manifest#

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <types>
        <members>Executive_Revenue_Velocity_Dashboard</members>
        <name>AnalyticsDashboard</name>
    </types>
    <version>68.0</version>
</Package>

SFDX CLI Retrieval & Deployment#

Retrieve and deploy AnalyticsDashboard metadata via the Salesforce CLI:

# Retrieve all AnalyticsDashboard components
sf project retrieve start --metadata "AnalyticsDashboard:*"

# Deploy a specific AnalyticsDashboard to the target org
sf project deploy start --metadata "AnalyticsDashboard:Executive_Revenue_Velocity_Dashboard"

Senior Architect Best Practices & Gotchas#

• Avoid Hardcoded Dataset Version IDs: When promoting dashboards across sandboxes, ensure dataset references resolve by DeveloperName (alias) rather than org-specific dataset version IDs (0Fb... / 0Fc...).
• Deploy Parent Application Folder First: Always include the parent Analytics Application folder in your deployment manifest; deploying an AnalyticsDashboard that references a missing application will fail validation.
• Row-Level Security Predicates: Verify that the underlying datasets referenced by your AnalyticsDashboard enforce row-level security predicates or sharing inheritance before embedding the dashboard on broad Lightning App Pages.

Frequently asked questions

How does AnalyticsDashboard differ from the standard Dashboard metadata type?

Standard Dashboard metadata represents operational Salesforce reports-based dashboards, whereas AnalyticsDashboard represents advanced analytics dashboards built on datasets and multi-step queries.

Where are AnalyticsDashboard files stored in an SFDX project?

They are stored in force-app/main/default/analyticsDashboards or wave/ directories depending on the analytics bundle structure.

Why do AnalyticsDashboard deployments fail when moving between sandboxes?

Deployments fail if the referenced analytics application folder, dataset, or custom fields used in dashboard steps do not yet exist in the target org.

How do I retrieve AnalyticsDashboard metadata using the Salesforce CLI?

Run sf project retrieve start --metadata AnalyticsDashboard to retrieve analytics dashboard definitions into your SFDX workspace.