Preserving CRM Analytics Dashboard Formatting When Deploying

You've built a beautiful CRM Analytics full of customization such as table column names, formats, and conditional formatting by grouping value.

Now, it's time to move this to production.  You can either deploy from the sandbox with change sets or use the Metadata API with your preferred tooling.  It's rather straightforward to select the dashboard name and complete the deployment. 

Except there's a problem. All that super styling work you did is gone. You're left with a sad looking dashboard.

What went wrong and how can we fix it? We need to dive behind the scenes of CRM Analytics to understand where our customization are stored.

Dataset XMD

Customizations made to fields in a dataset are stored as Extended Metadata or XMD.  When you make changes in Field Panel when exploring a dataset, the customizations are stored as XMD.  If you want to learn more about what you can do with XMD, check out Colors, labels, values – oh my! by SalesforceBlogger.com

Changes to the label, format, color or action menu are written to the file in JSON format or XML when downloaded as Metadata. Fortunately, we don't need to go into the details of JSON or XML to solve this issue.

As it's a separate file, you will see it as a separate Metadata Type. For example, when creating a Change Set. The Analytics Dataset Metadata will list out the Dataset XMD. The name of the XMD file matches the Dataset.

If you are working with the Metadata API, the Metadata Type is actually WaveXMD, which reflects one of the many prior names for CRM Analytics.  Just like edgemart transform in a dataflow to pull a dataset reflects the early EdgeSpring name. 

 

You can also access the Dataset XMD file from Analytics Studio by editing a dataset and using the Download action from the menu.  As it's JSON, you can make changes to the file and then upload the modified file with the Replace option.

So when you move a dataset from one environment to another, be sure to also include the related dataset xmd. 

But our issue is with the dashboard, so let's see how this concept applies.

Dashboard XMD

Guess what, many of the dashboard customizations are now stored in a separate XMD related to the dashboard. The changes to our table column names, conditional highlighting, color formats and more are all stored in this file.  When moving the dashboard, you have to include the dashboard XMD or the customizations will be lost.

The easiest place to find the Dashboard XMD is through a change set, although it is not obvious at first. There is not a Analytics Dashboard Metadata type. Instead the Dashboard XMD is stored with the Analytics Dataset XMD. 

Simply select it from the list, or use the View/Add Dependencies to see the related Metadata types.

Notes

There are a few additional considerations for accessing the Metadata from Change Sets.

• Dashboards and related Dashboard XMD in My Private App will not display as an available component.
• The Dashboard XMD will be based on the first dashboard save and API name at the time.  If you change the dashboard display name, the API name and associated Dashboard XMD will not change. 
• If the Dashboard can be saved with the same name as a Dataset. However, the XMD names must be unique. The Dashboard XMD will have a number added to the end. In our example, it would be Super_Style1
• This situation also applies to saved Lenses/Queries, as they have Lens XMD too.

Dashboard XMD & Metadata API

If you use the Salesforce CLI, continuous integration or deployment tool, you need to include the Dashboard XMD as well. This path isn't quite as obvious.

It seems the main difference between dataset and dashboard is the Dashboard XMD has a type of Asset.  Although there is a Asset Xmd Resource in the CRM Analytics REST API Developer Guide, it's only useful for viewing the Dashboard XMD.  You cannot deploy to it.

When using VS Code and the Org Browser to see Wave XMD metadata, only the Dataset XMD displays.  The Dashboard XMD is not there. I would love to see the CLI improved to display the Dashboard XMD or even include the ability to pull the related Dashboard XMD files automatically.  

Instead, you have to build a command manually to pull it.  Assuming you are using the default org, specify the WaveXMD Metadata Type and the name of your Dashboard XMD file.

sf project retrieve start -m 'WaveXmd:Super_Style'

The Metadata file will be stored in the Wave folder of your project.

For deploying, you have to build the counterpart command. Again, specify the Metadata Type and Dashboard XMD file name.

sf project deploy start -m 'WaveXmd:Super_Style'

Now your dashboard customization move with the dashboard from one environment to another!

Dashboard XMD Bonus

Have you ever worked in the Dashboard JSON and made changes to step names? I often try to give nodes more meaningful names in order to make bindings easier.  If that step already has customizations stored in the Dashboard XMD, the dreaded formatting rules will be lost message displays and I have to manually reapply my changes.

Now, with the ability to retrieve and deploy the Dashboard XMD, I can make the same change in the JSON. In my example, the step was changed from lens_1_1 to ByState.  I can now adjust the XML in the downloaded metadata file, by changing the field node to the new name - ByState.ALL

<dimensions>

<conditionalFormatting>

<property>chartColor</property>

<referenceField>Building.State_Prov_Name__c</referenceField>

<sortIndex xsi:nil="true"/>

<type>categories</type>

</conditionalFormatting>

<field>lens_1_1.ALL</field>

<isDerived>false</isDerived>

<sortIndex>0</sortIndex>

</dimensions>

Another node worthing knowing is waveVisualization.  This is what links the XMD to the Dashboard, based on the Dashboard API name.

Notes

• Be sure to save the Dashboard before deploying the modified Dashboard XMD, or there will be a deployment error that the field does not have corresponding step in its parent Asset.
• Dashboard bundle caching can prevent the changes from immediately displaying.  Either wait until the cache refreshes Or perform a log out/log in 
• You can also disable the caching (probably not a great idea for production).  This option is under Analytics Settings in Setup.