Migrating Workbooks and Data Sources that use Extracts

Tableau Server users can publish extracts which are copies, or subsets of the original data. These extracts may be embedded in a workbook or a data source. By default, when you use the Tableau Content Migration Tool to migrate a workbook or data source that contains an extract, that extract is migrated along with the workbook or data source that contains it. The Content Migration Tool gives you a couple options for controlling this behavior:

  • Switching to a Live Connection

    You can add the Remove Extract transformation to your migration plan to remove the extract from your workbook or data source during migration. As always, the source workbook or data source will not be modified. The copy of the workbook or data source migrated to the destination server will have the extract removed from it. This effectively switches the data connection back to a live connection.

Refreshing Extracts after Migration

You can enable the Refresh Extracts After Migration option in your migration plan to have an immediate extract refresh task scheduled after the workbook or data source is migrated.

We don't recommend using the Refresh Extracts After Migration option if your migration plan also uses the Set Connection Info transformation to change the data connection’s to point to a different set of data (for example, a different database server or database). When you change the connection information to point to different data and use the Refresh Extracts After Migration option, this can unintentionally expose data in a way that is a potential security issue.

Changing data connections that use extracts

Tableau data connections are either live connections that directly query a data source, or they are extracts of a data source. Extracts are copies or subsets of the original data and can be embedded in a workbook or data source. When present, the views will query data from the extract instead of the underlying data source.

Commonly, you’ll want to modify the data source connection during the migration so that it points to a different database on the destination server than it did on the source server.

For example, if you are migrating a workbook from your staging server to your production server, you will likely want to update the data connections inside the workbook to connect to your production database. You can implement this by using the Content Migration ToolSet Connection Info transformation in your migration plan. Now you have a migration plan which copies a workbook from staging to production and updates the data connections to point to the production database.

If your workbook’s data source uses an extract then you need to do a bit more work. In the current scenario, the workbook will be migrated and the live data connection updated, but the workbook’s views will still be showing the data from the staging database because the workbook still contains same extract of the staging database which it was using when it was copied from the source (staging) server. There are a few ways to address this.

Option 1: Use Published Data Sources

You can change your workbooks so that they use published data sources instead. This way, the extract will be managed as part of the published data source and migrating updates to the workbooks that use that data source can be simplified by not having to worry about the connection to the live database or the data extract.

Option 2: Remove the Extract During Migration

You can add a Remove Extract transformation to your migration plan. This will remove the extract from your workbook, effectively switching the data source to a live connection.

Option 3: Refresh the Extract After Migration

You can use the Refresh Extracts After Migrationoption in your migration plan. This will migrate the extract along with workbook but will schedule an immediate extract refresh task for that workbook after the migration is complete.

This option is usually not recommended when used in combination with a Set Connection Info transformation because of potential security issues that it can introduce.

The issue is that the migrated workbook on your destination server will still show the old (source) extract data for the period of time between the completion of migration and the completion of the extract refresh task. If the extract refresh task fails, then the old/source extract data will remain until the extract is refreshed.

In a scenario like we’ve outlined above, migrating from a staging to production environment, this may be acceptable but you should be aware that the users of your workbooks may not be aware that the workbook is showing old/staging data due it being recently migrated and the extract not being refreshed yet.

In other scenarios where you may be using Set Connection Info to change data connections to point to a different set of customer or client data, this could introduce serious security issues where the workbook’s extract contains data from a different client or customer until the extract has been refreshed post-migration.

One way to mitigate this issue is to implement a 2-stage migration. This approach requires you to create two migration plans, one for each step described below and ensures the workbooks and data sources have an up-t-o-date extract before they are accessible.

  • Stage 1: Migrate your content to a project on your destination site that only administrators have access to. This migration allows you to use the Refresh the Extract After Migration option along with the Set Connection Info transformation to update the data connection, because no unauthorized users will have an opportunity to see the old data, even if the extract refresh fails.
  • Stage 2: After stage 1 is complete and you confirm there is a successful extract refresh, run a second migration plan to migrate the content from the stage 1 destination to the final destination where it is visible to end-users.

Who can do this

Tableau Server user with an Explorer role or higher. To migrate content, you must have View and Download Workbook/Save a Copy permissions on the source site, and Publishing rights for the destination site. For more information, see Permissions.

Thanks for your feedback!