Uncovering Deployment Techniques for Tableau CRM

Tableau CRM is a brilliant tool for data exploration and for AI-driven advanced analytics. It’s intuitive in nature, easy to learn, and empowers users to quickly spin up applications, dashboards using pre-built templates. While TCRM in itself is a great tool, deploying TCRM components from one org to another may seem a bit tricky.

In this blog, I will talk about what metadata deployment is, mention some of the tools which use metadata API for deployment (tools like changesets, ANT, etc), Tableau CRM components which can be deployed, and also about managing the ones which cannot be deployed as of today (Spring 21). By the end of this blog, whether you’re a salesforce admin or a developer or in DevOps role, you’d be in a position to push your Tableau CRM project from your source org to production or UAT sandbox, or to any other salesforce org.

What is metadata deployment?

In simplified terms, metadata deployment is copying your source org’s metadata file – called a retrieved package, and pasting it in your target org – is called the deployed package. Metadata files in the target org get created if they’re absent; if present in the target, they are overwritten with source’s metadata files. Simple, right? And what is a metadata file you ask? Think of it as a file that describes your data. For example, Consider an opportunity record you created a few days ago. Against close date, you entered some date; against stage you entered some value. You also entered the opportunity name and populated the account this opportunity belongs to. All the information you are entering is your data which makes up your opportunity, whereas the fields against which you’re entering those values are the opportunity metadata.

Note: Metadata deployment moves only metadata from one org to another, and not your data.

Salesforce doesn’t expect you to manually copy and paste the metadata files one at a time. Instead, salesforce provides a bunch of metadata APIs which you can use to retrieve and deploy multiple components at once, thus making your task easier. In fact, there are a couple of tools out there that leverage metadata APIs, and help you retrieve and deploy components in a matter of a few clicks. Some of the tools are:

1. Changesets
2. Workbench
3. ANT Migration tool
4. Eclipse
5. Visual Studio Code

All the above-mentioned tools work on the principle of retrieve and deploy using package.xml manifest. The package.xml file is a project manifest that lists all the components you want to retrieve or deploy in a single request.

In this blog, I’d be using workbench for retrieval and deployment. But you can use any other tool you are comfortable with. All the tools I know of, work with package.xml manifest in the backend, and in the latter part of this blog, you’ll see how to create one for TCRM components.

What all you need to get started?

To get the most out of this blog, use two different orgs. One would be your source of retrieval and another would be your deployment target org. Note, these two do not need to be related orgs. You can retrieve the metadata from one org and simply deploy it to another, provided dependencies are taken care of.

Also, make sure that the user you’re using to retrieve /deploy has ‘Manage Analytics’, ‘API enabled’, and ‘Modify Metadata Through Metadata API Functions’ or ‘Modify All Data’ permissions. If you want, you can open access to wave API to anyone using the setting ‘Grant all users access to Wave API‘.

You can run the following queries to get a list of profiles/permission sets with the above-mentioned permissions. This will help you assign profile/permission sets necessary to proceed with retrieval/deployment:

1. Manage Analytics:

SELECT Id, Name, Label FROM PermissionSet WHERE PermissionsInsightsAppAdmin = true

2. API enabled:

SELECT Id,Name, Label FROM PermissionSet WHERE PermissionsApiEnabled = true

SELECT Id,Name FROM Profile WHERE PermissionsApiEnabled = true

3. Modify Metadata Through Metadata API Functions:

SELECT Id, Label, Name FROM PermissionSet WHERE PermissionsModifyAllData = true

SELECT Id, Name FROM Profile WHERE PermissionsModifyAllData = true

Let’s get started

Deployment is a three step process, steps being:

1. Pre-migrations steps
2. Deployment
3. Post-migration step

Pre-migration steps

Pre-migration steps are the steps you’d perform before proceeding with your deployment. Salesforce’s deployments are intelligent; i.e. they check the metadata dependencies and if any component is missing, they throw deployment error. For example, let’s say you created a dataset using a CSV file and have used it in the dashboard. Now, if the dataset is missing from your .zip file (the file you’ll use for deployment, which we’ll see in the next section) or is not present already in the target org, your deployment will fail with the error – “No Dataset found for Developer Name: XXX” where XXX is the dataset’s API name. But including this dataset in your .zip file will help you successfully deploy your components.

Let your errors guide you to missing components. As long as the metadata is present in your .zip file or in your target org, you’re good to proceed with your deployment.

Package Creation, Retrieval and Deployment

Now that you have all necessary permissions and the org setup in place, and have taken care of pre-migration steps(if at all any), you can get started with package creation.

While the majority of the Tableau CRM assets can be deployed, some cannot be as of today and these are the ones which you’d have to create/update manually. Use the list below to create package.xml which meets your requirements, and to create post-migration steps (if any):

Here’s a sample package.xml which you can use to retrieve above mentioned metadata from the source org:

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <types>
        <members>EclairGeoData_1</members>
        <name>EclairGeoData</name>
    </types>
    <types>
        <members>WaveApplication_1</members>
        <name>WaveApplication</name>
    </types>
    <types>
        <members>Sales_Metric_Analysis</members>
        <name>WaveDashboard</name>
    </types>
    <types>
        <members>WaveDataflow_1</members>
        <name>WaveDataflow</name>
    </types>
    <types>
        <members>WaveDataset_1</members>
        <name>WaveDataset</name>
    </types>
    <types>
        <members>WaveLens_1</members>
        <name>WaveLens</name>
    </types>
    <types>
        <members>WaveRecipe_1</members>
        <name>WaveRecipe</name>
    </types>
    <types>
        <members>WaveTemplateBundle_1</members>
        <name>WaveTemplateBundle</name>
    </types>
    <types>
        <members>WaveXmd_1</members>
        <name>WaveXmd</name>
    </types>
    <types>
        <members>Maximise_Sales_Price</members>
        <name>DiscoveryAIModel</name>
    </types>
    <types>
        <members>Sales_Prediction</members>
        <name>DiscoveryGoal</name>
    </types>
    <types>
        <members>WaveComponent_1</members>
        <name>WaveComponent</name>
    </types>
    <version>51.0</version>
</Package>

Here you can specify the API names of each metadata component in between <members></members> tag, and the <name></name> tag defines the metadata type of the component. If you’re unsure of what is the API name of the component, you can always invoke REST explorer to get a list of Tableau CRM assets. For example, you can run the following piece of code in GET method and get relevant details of a dashboard:

/services/data/v48.0/wave/dashboards/0FKxxxxxxxxxxxxx

where 0FKxxxxxxxxxxxxx is your dashboard ID. If you find this a bit tiresome, then you can always figure out API names using workbench’s ‘Metadata Types & Components’ list (in the info section menu) – this is what I use as well.

Note: It has been established that a component (mentioned between <members></members>) is an instance of a metadata type (mentioned between <name></name>). “Analytics” and “EAC” are 2 components of “Settings” metadata type. If you wish to retrieve and/or deploy these settings, then add the following to your package.xml:

<types>
<members>Analytics</members>
<members>EAC</members>
<name>Settings</name>
</types>

WaveXmds

‘Metadata Types & Components’ section of workbench or REST API will get you a list of all metadata types mentioned above except the WaveXmds. But as a thumb rule, the dataset XMD’s API name would be the same as the dataset’s API name. You can always cross-check in the Dataset edit window.

So you can use the dataset’s API name for WaveXmd of datasets. Similarly, for dashboards, the associated XMD’s API name would be the dashboard’s API name. Dashboard XMD store conditional formatting you do on your charts or tables or numbers etc.

Consider a dashboard with API name ‘Test_Dashboard_1’ and a dataset with API name ‘Best_Dataset_1’, and if you had to retrieve the XMDs of dataset and dashboard, then your package.xml will look like this.

    <types>
        <members>Test_Dashboard_1</members>
        <members>Best_Dataset_1</members>
        <name>WaveXmd</name>
    </types>

Package.xml generation

Trust me, package.xml generation is the most crucial part of any deployment.

Once you have package.xml in place, all that is left to do is:

1. Login to workbench using your source org’s credentials.

2. Upload your package.xml in the Retrieve window:

3. Click on ‘Next’ and then on ‘Retrieve’. Download the retrieved zip file. You’ll use this zip file to deploy to your target org.

Once you have successfully retrieved and downloaded the .zip file, you’re ready to deploy these components in your target org.

4. Log into workbench using your target org’s credentials

Note: Its a good practise to keep a back-up of your target org’s metadata, especially of production org. You can do this by simply retrieving the package.xml’s components from target org and storing the zipped file away.

5. Upload your .zip file in the ‘Deploy’ window

Note: Enabling ‘Check Only’ checkbox ensures that you’ll ‘Validate’ your deployment; i.e. you won’t deploy your components into your target org, but will check your components for deployment failures. This is a rather handy option when you want to make sure that you’re package will get deployed without errors in production instance, on the day of Go-Live.

Rollback On Error ensures that if there’s a single deployment failure, not a single component of the uploaded .zip file will get deployed. Uncheck this button to allow ‘partial deployments’ – this is not a good practise though, but you can use it if you know the implications of partial deployment

For deploying Tableau CRM components, you do not have to run any test classes

6. Click on ‘Next’. Hover over your name in workbench and make sure you’re in the right org and are logged in with the right user (make this a mandatory check as deployments are permanent in nature).

7. Click on ‘Deploy’.

So, in these easy 7 steps, you have deployed your entire TCRM project to a different org. Isn’t it really easy?

I have realised over the years that “All the answers lie in the retrieved XML”. This is one golden rule I adhere to whenever I get deployment errors, or retrieval warnings, or am simply not sure of the dataflow associated with a recipe. I’d strongly recommend that you take one good look at the content of the main files and metafiles.

Post-migration Steps

Post-migration steps are the steps you’d perform once the deployment is through in an org. Below you will see a checklist you can run through and use what is appropriate for your deployment.

• Create your external datasets using CSVs or run Analytics Connectors, if any
• If you’re using a custom object which requires data insert/upsert/update, do the data manipulations so that the dataflow can pick it up
• The process of deployment moves your metadata and not your data. So, once you deploy your dataflows/recipes, run them so that data can be populated in your datasets.
• Security Predicates/Sharing inheritance cannot be deployed as of today. So, update them manually
• Schedule the dataflow/recipes/syncs manually, if need be
• If you’re using an image in your dashboard, upload it manually
• Do a smoke test
  • Check if every component has moved or not
  • Play around for a while and see if anything is breaking in the components you deployed
  • Make sure that the datasets are present in the correct application
  • See if the application is indeed shared with the right set of people
  • Keep a keen eye on conditional formatting, and dataset XMD. Verify if they have moved.

Pro tips

Below are some tips to keep in mind to make the deployment process smoother.

1. Recipes have a dataflow associated with them, which is not visible through UI. The metafile of the recipe contains the API name of the dataflow associated with it. Make sure to retrieve this dataflow as well in order to ensure that all the recipe related changes are moved to target org
2. As recipes are built upon existing dataset, make sure that the dataset is either present in your target org or you’re deploying it
3. It’s a good practice to develop in a dev environment with very little data and then migrate components to org with larger data volume where you can validate the data accuracy, do QA with power users and/or performance tests. Once the results are satisfactory, you can deploy the same package to production.
4. Your dataflow run/data sync will fail if the integration user doesn’t have access to a field used in the dataflow. So make sure you’re deploying relevant permissions on Integration User’s profile/permission sets assigned to the user.
5. If you’re using the ‘User’ Object’s field in your security predicates, make sure that the Security user has got access to the field, or you may get errors or random results.
6. The dataset creation step can both be a pre- and post-migration step. Why you ask? Well, your dashboard will display an error message upon load until the datasets used in the dashboard are populated with data. And if the dashboard is already rolled out to users, then such an error can throw users off. So, you’d either have to create the dataset as a pre-migration step or as a post-migration step if you can have dashboard downtime. Plan accordingly.
7. Check out this really helpful tool by salesforce labs – Tableau CRM Data Catalog. This is an excellent tool to understand the lineage of Tableau CRM assets. Want to learn how to use it? Check out this excellent blog by Rikke!

Written by