WaveLens Metadata Type Guide

Architectural Overview#

The WaveLens metadata type represents a saved visualization or exploratory query on a CRM Analytics dataset. In the analytical lifecycle, lenses serve as targeted data investigation assets—allowing data scientists, business analysts, and executives to slice, dice, group, and visualize metrics before incorporating them into comprehensive multi-widget dashboards (WaveDashboard).

Architecturally, a WaveLens decouples its administrative metadata envelope from its exploratory query state. The metadata XML file establishes folder ownership and naming conventions, while the companion JSON file encapsulates query logic (SAQL strings or compact form parameters), measure aggregations, grouping dimensions, and visual chart rendering properties.

For release architects, understanding how WaveLens references target datasets and application folders ensures smooth transitions between developer scratch orgs, sandboxes, and production environments.

Directory and File Suffix#

In Salesforce DX projects, WaveLens components are stored under the wave/ directory as paired files:

• Visualization and Query JSON: force-app/main/default/wave/<LensName>.wlens
• Metadata Configuration File: force-app/main/default/wave/<LensName>.wlens-meta.xml

force-app/
└── main/
    └── default/
        └── wave/
            ├── Quarterly_Bookings_Trend.wlens
            └── Quarterly_Bookings_Trend.wlens-meta.xml

Key Metadata Fields#

The .wlens-meta.xml metadata descriptor governs administrative properties:

The companion .wlens file contains the complete JSON payload defining:

• state.query: The SAQL string or compact form query specifying filters, groups, and aggregations.
• state.visualizationType: Chart presentation properties and axis formatting.
• state.layout: Layout sizing and legend positioning.

Declarative XML and JSON Examples#

Metadata XML Descriptor (wave/Quarterly_Bookings_Trend.wlens-meta.xml)#

<?xml version="1.0" encoding="UTF-8"?>
<WaveLens xmlns="http://soap.sforce.com/2006/04/metadata">
    <application>Executive_Commercial_Hub</application>
    <datasets>
        <dataset>Global_Sales_Metrics</dataset>
    </datasets>
    <description>Quarterly comparison of closed-won bookings segmented by global geographic region.</description>
    <masterLabel>Quarterly Bookings Trend</masterLabel>
    <visualizationType>hbar</visualizationType>
</WaveLens>

Accompanying Lens Definition (wave/Quarterly_Bookings_Trend.wlens)#

{
  "version": "68.0",
  "state": {
    "query": {
      "measures": [["sum", "Amount"]],
      "groups": ["FiscalQuarter", "Region"],
      "filters": [
        ["StageName", ["Closed Won"], "in"]
      ]
    },
    "visualizationType": "hbar",
    "parameters": {
      "title": "Closed Won Bookings by Region",
      "legend": {
        "show": true,
        "position": "right"
      },
      "axisMode": "grouped"
    }
  },
  "datasets": [
    {
      "name": "Global_Sales_Metrics"
    }
  ]
}

Manifest Definition (package.xml)#

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

Retrieval and Deployment#

Retrieving Lenses via Salesforce CLI#

Retrieve the lens query definition and metadata descriptor together:

# Retrieve a single lens component
sf project retrieve start --metadata "WaveLens:Quarterly_Bookings_Trend"

# Retrieve all lenses and datasets within the project
sf project retrieve start --metadata "WaveDataset,WaveLens"

Validating and Deploying across Orgs#

Deploy lenses into target testing or production orgs:

# Validate deployment without applying changes
sf project deploy validate \
    --metadata "WaveLens:Quarterly_Bookings_Trend" \
    --target-org uat-sandbox

# Execute deployment to target org
sf project deploy start \
    --metadata "WaveLens:Quarterly_Bookings_Trend" \
    --target-org production-org

Inspecting Lens Records with Tooling API#

Enterprise CI/CD systems can verify deployed lenses using Tooling API queries:

sf data query --use-tooling-api --query \
    "SELECT Id, DeveloperName, MasterLabel, FolderId, VisualizationType, CreatedDate FROM Lens WHERE DeveloperName = 'Quarterly_Bookings_Trend'"

Architect Deployment Best Practices & Gotchas#

Frequently asked questions

What files represent a WaveLens in Salesforce DX?

A WaveLens is represented by a wlens JSON file containing query specifications, visualization properties, and chart configurations, paired with a wlens-meta.xml metadata file.

How do you resolve dataset dependencies when deploying WaveLens?

The target org must contain the source WaveDataset referenced by the lens query. Deploy datasets and run their respective data pipelines prior to deploying dependent lenses.

Can a WaveLens be clipped into a WaveDashboard?

Yes, lenses serve as exploratory scratchpads whose SAQL or compact queries and chart configurations can be copied or clipped directly into dashboard widget steps.

What permissions are required to deploy WaveLens metadata?

The deploying user or continuous integration service principal requires CRM Analytics Admin permissions or specific Analytics Cloud metadata deployment system privileges.