WaveXmd Metadata Type Guide

Architectural Overview#

The WaveXmd metadata type represents Extended Metadata (XMD) for a CRM Analytics dataset. In enterprise reporting, raw dataset columns generated from ETL processes frequently retain technical database aliases, inconsistent currency symbols, or arbitrary default colors. WaveXmd provides an abstraction layer that governs how dataset fields are presented to end-users without altering the underlying parquet or edgemart data store.

Architecturally, WaveXmd decouples data processing from data presentation. While recipes (WaveRecipe) and dataflows (WaveDataflow) focus on record joining and data transformation, WaveXmd controls human-centric presentation attributes: formatting measures with currency prefixes, establishing corporate brand color palettes for dimension picklist values, localizing field labels, and hiding system surrogate keys from the Lens query builder.

By maintaining WaveXmd definitions in source control, DevOps teams ensure that corporate design systems and executive visual standards persist across environment refreshes and CI/CD deployments.

Directory and File Suffix#

In Salesforce DX project structure, WaveXmd components are located in the wave/ directory and use the .xmd-meta.xml file suffix, named after the associated dataset:

• Source File Path: force-app/main/default/wave/<DatasetName>.xmd-meta.xml

force-app/
└── main/
    └── default/
        └── wave/
            ├── Global_Sales_Metrics.wds-meta.xml
            └── Global_Sales_Metrics.xmd-meta.xml

Key Metadata Fields#

The root <WaveXmd> element encapsulates sub-arrays configuring individual field categories:

Dimension & Measure Sub-Properties#

• field: The exact API name of the dataset field being customized.
• label: The customer-friendly field label shown in Analytics Studio.
• format: For measures, specifies the number format pattern (such as "$#,##0.00").
• members: For dimensions, defines specific picklist value overrides (member, label, color).
• isDerived: Boolean indicating whether the field is derived at runtime.

Declarative XML Examples#

Complete Extended Metadata File (wave/Global_Sales_Metrics.xmd-meta.xml)#

<?xml version="1.0" encoding="UTF-8"?>
<WaveXmd xmlns="http://soap.sforce.com/2006/04/metadata">
    <dataset>Global_Sales_Metrics</dataset>
    <dimensions>
        <field>StageName</field>
        <isDerived>false</isDerived>
        <label>Sales Pipeline Stage</label>
        <members>
            <color>#2E844A</color>
            <label>Closed and Booked</label>
            <member>Closed Won</member>
        </members>
        <members>
            <color>#BA0517</color>
            <label>Opportunity Lost</label>
            <member>Closed Lost</member>
        </members>
    </dimensions>
    <measures>
        <field>Amount</field>
        <formatDecimalSeparator>.</formatDecimalSeparator>
        <formatThousandsSeparator>,</formatThousandsSeparator>
        <isDerived>false</isDerived>
        <label>Booked Revenue</label>
        <formatCustomFormat>[&quot;$#,##0.00&quot;,1]</formatCustomFormat>
    </measures>
    <type>Main</type>
</WaveXmd>

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>Global_Sales_Metrics</members>
        <name>WaveXmd</name>
    </types>
    <version>68.0</version>
</Package>

Retrieval and Deployment#

Retrieving Extended Metadata via Salesforce CLI#

Retrieve the dataset extended metadata along with its parent dataset:

# Retrieve a specific WaveXmd component
sf project retrieve start --metadata "WaveXmd:Global_Sales_Metrics"

# Retrieve all datasets and their XMD configurations
sf project retrieve start --metadata "WaveDataset,WaveXmd"

Deploying across Release Pipelines#

Deploy the updated extended metadata definitions into your sandboxes or production org:

# Validate XMD syntax against target org
sf project deploy validate \
    --metadata "WaveXmd:Global_Sales_Metrics" \
    --target-org staging-sandbox

# Deploy the XMD configuration
sf project deploy start \
    --metadata "WaveXmd:Global_Sales_Metrics" \
    --target-org production-org

Architect Deployment Best Practices & Gotchas#

Frequently asked questions

What is the primary architectural purpose of WaveXmd?

WaveXmd allows architects to customize visual presentation, number formatting, colors, and field labels for datasets without having to alter underlying dataflow or recipe definitions.

How does WaveXmd handle currency and number formatting?

Within the measures element, WaveXmd specifies format strings such as custom currency symbols, decimal precision, and percentage formats displayed across dashboards.

What happens to WaveXmd customizations when a dataset is re-run?

User XMD metadata deployed through the Metadata API persists across dataset refreshes, ensuring continuous branding, custom colors, and friendly dimension labels.

How is a WaveXmd file named in a Salesforce DX project?

The WaveXmd file name follows the convention of the dataset developer name combined with the xmd suffix, located in the wave folder with an xmd-meta.xml extension.