Tableau Content Migration Tool Use Cases

Tableau Content Migration Tool as the name suggests, is primarily used for moving Tableau Server content from one site to another. However there are many features in the tool that makes it ideal for accomplishing several tasks related to content migration and maintenance.

Note: In many of the use cases we use the term migration to describe moving content from one environment, site, or project to another. However, technically the Content Migration Tool copies content and does not automatically delete or archive the original or source content.

The uses cases describe below are some common use cases that the Content Migration Tool is useful for:

Content Promotion

You can use the Content Migration Tool to create content in development sites and do routine migrations to staging or production environments.

Use the following steps to promote content to production environments:

  1. Create a plan and select the site used for development as the source and the staging or production site as the destination. For more information, see Create a Plan in Migration Plan Overview topic.

  2. Select the content you want to migrate from your source site. You can select entire projects, specific workbooks and data sources, and user permissions. For more information, see Planning in Migration Plan Overview topic.

  3. If you need to make any changes or transformations to the content during this migration, you can configure that in the plan as well. This is referred to as Mapping. The types of mapping you can make include:

    • Changes to workbooks: including renaming workbooks and changing destination project. For a full list of workbook transformations, see Migration Plans: Workbooks.

    • Changes to data sources: Includes replacing table or schema names, settings calculation formulas, and setting connection information. For a full list of data source transformations, see Migration Plans: Workbooks (embedded data sources) and Migration Plans: Workbooks (published data sources).

    • Changes to Users: Includes domain, user, and group name changes in the destination.

  4. When you are ready, click on Verify & Run to end the Planning phase of your migration and prepare to run your plan.

  5. To schedule this to run on a regular basis, you can script this as a job using the Content Migration Tool Runner and schedule it. For more information on using the Content Migration Tool Runner, see, Using the Tableau Content Migration Tool Console Runner.

Tailoring Content for Customers

When working in a consulting scenario, you can customize content for each of your customers using the Content Migration Tool. Each workbook functions as a template for your migration plan, allowing you to apply styling (text, images, etc.) and replace data sources for specific customers.

Use the following steps to customize content for your customers:

  1. Create a plan and select the production site as the source and the customer site as the destination. For more information, see Create a Plan in Migration Plan Overview topic.

  2. In the Workbooks step of the Migration Plan, use workbook mappings and transformations to customize your content. Below are two examples of frequently used transformations. For a full list of workbook transformations, see Migration Plans: Workbooks.

    • To personalize content, you can use the Replace Image and Replace Text transformations to update the workbook with a customer's company name and logo.

    • When it comes to data sources, you can use the Replace Table/Schema Name or Set Custom SQL transformations to modify content for your customer.

  3. Verify and run the plan. When you are ready, click on Verify & Run to end the Planning phase of your migration and prepare to run your plan.

Content Migration

You can use the Content Migration Tool to migrate content between Tableau Server deployments.

Use the following steps to migrate content between Tableau Server deployments:

  1. Create a plan and select the site you want to migrate from as your source site. For more information, see Create a Plan in Migration Plan Overview topic.

  2. Select the content you want to migrate from your source site. You can select entire projects, specific workbooks and data sources, and user permissions.

  3. Create user permissions mappings to customize and secure content. For more information, see Migration Plans: User Permissions Mapping.

  4. Verify and run the plan. When you are ready, click on Verify & Run to end the Planning phase of your migration and prepare to run your plan.

Tips
- You can migrate your content in stages, test and validate content iteratively before final migration is complete. There is no server downtime when you use this method of migration. It can be a replacement for Site import/export.
- Content Migration Tool migration does not handle embedded credentials, subscriptions, and custom views. These will have to be migrated manually.

External Content Sharing

You can use the Content Migration Tool to share internal content with external collaborators, without allowing access to your site. This keeps your data secure and allows you to publish only select workbooks and data sources. Once content has been shared, collaborators sign in to their Tableau Server or Tableau Online site to view and make changes, without affecting content stored on your internal Server.

Before you continue, make sure the content you are sharing is compatible between the internal and external sites. The external site should typically be running the same release version (2019.X, 2020.X, etc) of Tableau Server or later. To learn more about compatibility, see Make Workbooks Compatible Between Versions in Tableau Desktop help.

Use the following steps to share content externally:

  1. Work with the external Tableau Online or Tableau Server administrator to determine a user account that has publishing rights on the external site. You will use this user account to create the migration plan. For more information, see Set Users’ Site Roles and Permissions.

  2. Prepare internal content. As a best practice, we recommend separating content on the internal server to a project, with locked permissions and strict governance rules. Workbooks and data sources should be clearly labeled to indicate the content is for external use. For more information, see Use Projects to Manage Content Access.

    Note: Content shared with external sites must use data extracts unless the data source is publicly accessible. For information about creating extracts and replacing data sources, see Extract Your Data and Replace Data Sources in Tableau Desktop help.

    If you have implemented row level security, those data sources must be updated to reflect user filters and other details for the external site. For more information about row level security, see Restrict Access at the Data Row Level in Tableau Desktop help.

  3. Create a plan and select the internal site as the source and the external Tableau Online or Tableau Server site as the destination. For more information, see Create a Plan in Migration Plan Overview topic.

  4. Select the content you want to share with the external site. You can select entire projects, specific workbooks and data sources, and user permissions.

  5. Verify and run the plan. When you are ready, click on Verify & Run to end the Planning phase of your migration and prepare to run your plan.

Validating Database Migrations

This use case is when you intend to validate content after a migration of the underlying databases. One example of database migration is moving from SQL Server to Snowflake. CMT can help you validate the content built from both data sources is the same before you finalize your migration, but it cannot perform the actual database migration.

Use the following steps to validate database migrations:

  1. Create a plan and select the Tableau Server site that you are going to use as your source. For more information, see Create a Plan in Migration Plan Overview topic.

  2. Select the content you want to change the data source or database connections and select a new project as the destination. Let’s call the source project as Project A, and the new or the destination project as Project B.

  3. Verify and run the plan. When you are ready, click on Verify & Run to end the Planning phase of your migration and prepare to run your plan.

  4. Update the content in Project B with the new database connections or replace the data sources. This needs to be done manually by authoring.

  5. Test each workbook in Project A with the copy in Project B and review for any inconsistencies in the data due to the change in data source.

  6. Once you have confirmed everything is working as expected, overwrite the content in Project A with the updated content in Project B.

Important! If the content already exists in the destination project and you do not select the overwrite option, the content will not be copied over to the destination project.

Geographical Content Migration

If you are maintaining a geographically distributed, multi-server environment, you will need some of this content to be the shared and available across all the servers. This use case describes how to migrate content between Tableau Servers in different geographies. The Tableau Server can be in the same country or across continents.

Best Practices:
- We recommend migrating content in one direction only meaning Primary to Secondary. Here we use the term Primary to indicate the source Tableau Server and Secondary to indicate the destination. You can have one or more destination.
- We recommend prioritizing the content that you most need in multiple geographies.

Use the following steps to migrate between Tableau Server that are distributed in different geographies:

  1. Create a plan on the Primary server. For more information, see Create a Plan in Migration Plan Overview topic.

  2. Select content that you want to share between the Primary and Secondary.

  3. Verify and run the plan. When you are ready, click on Verify & Run to end the Planning phase of your migration and prepare to run your plan.

  4. To schedule this to run on a regular basis, you can script this as a job using the Content Migration Tool Runner and schedule it. For more information on using the Content Migration Tool Runner, see, Using the Tableau Content Migration Tool Console Runner.

  5. Review the content on the source periodically to determine if new items should be added to the migration plan.

Maintenance Tasks

You can use the Content Migration Tool to perform a variety of maintenance tasks.

Tagging stale content

Using the Tableau Content Migration Tool, you can manage archiving stale content. For example, you can build a plan that runs on a regular schedule that can automatically pick up content tagged as Stale Content and move it to an Archive project. After a certain amount of time, the content in this project can be purged from the system. For more information see, Migration Plans: Workbooks.

Restoring content

You can use the Content Migration Tool to restore content removed (accidentally or purposefully) from the production Tableau Server with content from a backup Server. The restoration process is simple and does not require downtime, compared to restoring with a backup file.

Use the following steps to restore content from a backup Server:

  1. Create a plan and select the backup Tableau Server as the source and the production Server as the destination. For more information, see Create a Plan in Migration Plan Overview topic.

  2. Select the content you want to restore from the backup Tableau Server.

  3. Verify and run the plan. When you are ready, click on Verify & Run to end the Planning phase of your migration and prepare to run your plan.

  4. Review the content on the production Server.

Partial backup

If you follow a Disaster Recovery plan, the Content Migration Tool can be used to maintain a backup Tableau Server environment. You can use the Content Migration Tool to perform partial backups by transferring new content from production to the backup Tableau Server. Performing partial backups will keep your backup environment updated and ready for failover. If you have not configured a backup Tableau Server environment, see Disaster Recovery for Tableau Server whitepaper for more information

Note: Before you perform a partial backup, make sure you understand the Migration Limitations when using the Content Migration Tool. You may still need to periodically perform a full backup and restore to backup all Tableau Server content. For more information, see Perform a Full Backup and Restore of Tableau Server

Use the following steps to perform a partial backup of your content:

  1. Create a plan and select the backup Tableau Server as the source and the production Server as the destination. For more information, see Create a Plan in Migration Plan Overview topic.

  2. Select the content you want to backup. You can select entire projects, specific workbooks and data sources, and user permissions. To migrate only new content, make sure the publish options Overwrite Newer Workbooks and Overwrite Newer Data Sources are not selected. For more information, see Migration Plans: Workbooks.

  3. Verify and run the plan. When you are ready, click on Verify & Run to end the Planning phase of your migration and prepare to run your plan.

  4. To schedule this to run on a regular basis, you can script this as a job using the Content Migration Tool Runner and schedule it. For more information on using the Content Migration Tool Runner, see, Using the Tableau Content Migration Tool Console Runner.

Thanks for your feedback!