Tableau CRM REST API Developer Guide

Working with the Tableau CRM REST API
Tableau CRM REST API Overview
Backup and Restore Previous Versions of Tableau CRM Assets with History API
Run, Schedule, and Sync Tableau CRM Data with REST APIs
Build, Manage, Schedule, and Run Tableau CRM Recipes with REST APIs
Tableau CRM REST API Authentication
Tableau CRM Lightning Web Components
API End-of-Life
Tableau CRM REST API Reference
Additional Tableau CRM REST API Resources
PDF

Newer Version Available

This content describes an older version of this product. View Latest

Backup and Restore Previous Versions of Tableau CRM Assets with History API

When you edit Tableau CRM dashboards, lenses, recipes, and dataflows, Tableau CRM backs them up automatically. When you save a new version of an asset, Tableau CRM creates a snapshot of it. You can then preview snapshots and revert to previous versions using the REST History API.

Every time you save a new version of a dashboard, lens, recipe, or dataflow, Tableau CRM saves the older version. It also saves dashboard and lens conditional formatting.

Tableau CRM saves 20 versions of an asset, including 10 tagged and 10 untagged versions. When you save more than 20 new versions of an asset, Tableau CRM saves the new version and purges older versions. When the limit is reached and the save is for a tagged version, the oldest tagged version is purged. An untagged version save purges the oldest untagged version. To increase this limit, contact Salesforce and ask your representative to increase the org value Maximum analytics asset histories to track in the database, also known as AnalyticsMaxHistories.

You can add tags that describe asset versions to give you and other team members reminders of what's been changed and why. You can use either manual or automatic tagging.

Tableau CRM gives you two ways to manually tag an asset version.

  • When you save a dashboard or lens, the Save dialog displays a Version History box when you save a dashboard or lens. Enter a short description of your changes there. (Dataflows don't currently have a user interface for adding tags to previous versions.)The Version History field in the dashboard Save dialog
  • You can also tag changes with the public REST API. Use the API to tag history records with a description, which you can do even after saving the asset. You can edit existing descriptions.
    1*PATCH: /services/data/v46.0/wave/dashboards/0FKxx0000004CAeGAM/histories/0Rmxx0000004Cx2CAE*
2*REQUEST BODY: {"label" : "new description"}*
Tableau CRM automatically adds tags to history records in one of two ways.
  • When you create and save the initial version of an asset, Tableau CRM adds the tag Initial Create to the history record.
  • When you create or upgrade an app from a template, Tableau CRM tags history records for the newly created app. The tag includes the template action, template name, and the template version. This information helps you restore the correct previous version of an asset after you upgrade an app from a new template version.

Previewing and Reverting to Previous Asset Versions

To get a list of history records for an asset, either log in to Workbench and execute an API call. Or enter the appropriate command in the Salesforce Command Line Interface (CLI) with the Tableau CRM plugin:

A previous version of a dashboard may not work if assets that the version relies on have been removed from Tableau CRM. Those assets can be other dashboards, datasets, lenses, and images.

Warning

  • Dashboard history records.
    • Workbench call: 
      1GET: /services/data/v526.0/wave/dashboards/<dashboardId>/histories
    • CLI command: 
      1sfdx analytics:dashboard:history:list
  • Lens history records.
    • Workbench call: 
      1GET: /services/data/v52.0/wave/dashboards/<lensId>/histories
    • CLI command:sfdx analytics:lens:history:list
  • Recipe history records.
    • Workbench call: 
      1GET: /services/data/v52.0/wave/recipes/<recipeId>/histories
  • Dataflow history records.
    • Workbench call: 
      1GET: /services/data/v52.0/wave/dataflows/<dataflowId>/histories
    • CLI command:sfdx analytics:dataflow:history:list

Optionally, you can navigate to the History API endpoint from the URLs in the Asset Response (HATEOAS). The link is highlighted in the following dashboard detail response.Analytics Asset History API endpoint for dashboard restoration

Or manually execute the following REST calls from workbench:

  • Get a list of all dashboards:
    1GET: /services/data/v52.0/wave/dashboards
  • Find a particular dashboard, click its details URL in the response body:
    1GET: /services/data/v52.0/wave/dashboards/<dashboardId>
  • Get a list of histories, click the historiesUrl in the dashboard details response:
    1GET: /services/data/v52.0/wave/dashboards/*<dashboardId>/histories*

Preview a Previous Version

After listing asset version histories, preview the JSON for a version. During preview, you see the JSON as it looked when it was saved.

Use Workbench to preview the JSON for previous asset versions. Click the previewUrl in the response body.

Analytics Asset History API call for previous version preview

Dataflows have two preview URLs: previewUrl and privatePreviewUrl. The private preview URL provides the same JSON format as you’d see if you downloaded the JSON file declaratively using the Tableau CRM dataflow editor. The preview URL provides the public version of the JSON.

Note

Restore a Previous Version

After you confirm you’re previewing the correct asset version, restore it using either REST API calls or the CLI.

Using the REST process, navigate to the version you'd like to revert to and locate the revertUrl.

This REST URL requires a PUT call.

Note

Analytics Asset History API call to restore previous version
To restore an asset from the previous version, perform a PUT on the revertUrl.
1*PUT: /services/data/v52.0/wave/dashboards/*<dashboardId>/bundle**
2*REQUEST BODY: {"historyId": "<historyId>, historyLabel" : "optional description of new change"}*

Copy the historyId of the version you want to restore. You use it in the request body as shown here.

Analytics Asset History API call to restore previous version

The CLI commands for restoring assets are as follows:

  • Dashboards. sfdx analytics:dashboard:history:revert -i <dashboardid> -h <historyid>
  • Lenses. sfdx analytics:lens:history:revert -i <lensid> -h <historyid>
  • Dataflows. sfdx analytics:dataflow:history:revert -i <dataflowid> -h <historyid>

historyid is the id for the version of the asset you’d like to restore.

Limitations

When you restore the previous version of an asset, the asset may not run as expected. If the asset depends on other assets (for example, datasets) and those assets have been deleted or modified, you may get errors. However, every time you restore a previous version, you create a history record. You can always restore the last working copy.

When you delete an asset, all history is deleted with it, and you can’t undelete it.

Currently, Tableau CRM doesn’t back up previous versions of dataset XMD files.