Analytics REST API Developer Guide

Working with the Analytics REST API
Analytics REST API Overview
Backup and Restore Previous Versions of Analytics Assets with History API
Analytics REST API Authentication
Analytics REST API Reference
PDF

Newer Version Available

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

Backup and Restore Previous Versions of Analytics Assets with History API

When you edit Analytics dashboards, lenses, and dataflows, Analytics backs them up automatically. When you save a new version of an asset, Analytics 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 an Analytics dashboard, lens, or dataflow, Analytics saves the older version. It also saves dashboard and lens conditional formatting.

Analytics saves 20 versions of an asset, including 10 tagged and 10 untagged versions. When you save more than 20 new versions of an asset, Analytics saves the new version and purges the oldest one. To increase this limit, contact Salesforce and ask your representative to increase the org value 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.

Analytics 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"}*
Analytics automatically adds tags to history records in one of two ways.
  • When you create and save the initial version of an asset, Analytics adds the tag Initial Create to the history record.
  • When you create or upgrade an app from a template, Analytics 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 Analytics plugin:

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

Warning

  • Dashboard history records.
    • Workbench call: 
      1GET: /services/data/v46.0/wave/dashboards/<dashboardId>/histories
    • CLI command: 
      1sfdx analytics:dashboard:history:list
  • Lens history records.
    • Workbench call: 
      1GET: /services/data/v46.0/wave/dashboards/<lensId>/histories
    • CLI command:sfdx analytics:lens:history:list
  • Dataflow history records.
    • Workbench call: 
      1GET: /services/data/v46.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 dashboard detail response below.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/v46.0/wave/dashboards
  • Find a particular dashboard, click its details URL in the response body:
    1GET: /services/data/v46.0/wave/dashboards/<dashboardId>
  • Get a list of histories, click on the historiesUrl in the dashboard details response:
    1GET: /services/data/v46.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 Analytics dataflow editor. The preview URL provides the public version of the JSON.

Note

Restore a Previous Version

Once you’re sure 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/v46.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, Analytics doesn’t back up previous versions of recipes and dataset XMD files.