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 make 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 information below describes some common use cases where you can leverage the Content Migration Tool.
Content promotion
You can use the Content Migration Tool to create content for development sites and then perform routine migrations to promote content to staging or production environments.
Use the following steps to promote content to production environments:
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.
When migrating your workbooks between two projects on the same site, your sign-in credentials for the source and destination may be similar or identical. In this scenario, we recommend using personal access tokens for a more reusable connection. For more information, see Personal Access Tokens.
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.
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: Includes renaming workbooks and changing the 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: Published Data Sources (published data sources).
Changes to Users: Includes domain, user and group name changes in the destination.
When you are ready, click Run Migration to end the Planning phase and prepare to run your plan.
To schedule this to run regularly, 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 customise 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 customise content for your customers:
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.
In the Workbooks step of the Migration Plan, use workbook mappings and transformations to customise your content. Below are two examples of frequently used transformations. For a full list of workbook transformations, see Migration Plans: Workbooks.
To personalise 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.
Verify and run the plan. When you are ready, click Run Migration to end the Planning phase and prepare to run your plan.
Environment migration
You can use the Content Migration Tool to migrate content between Tableau Server environments.
Use the following steps to migrate content between Tableau deployments:
Create a plan and select the site you want to migrate from as your source. For more information, see Create a Plan in Migration Plan Overview topic.
Select the content you want to migrate from your source site. You can select entire projects, specific workbooks and data sources and user permissions.
Create user permissions mappings to customise and secure content. For more information, see Migration Plans: Permissions and Ownership.
Verify and run the plan. When you are ready, click Run Migration to end the Planning phase and prepare to run your plan.
Tips
- Before you perform an environment migration, make sure you understand the Migration Limitations when using the Content Migration Tool.
- You can migrate your content in stages, test and validate content iteratively before final migration is complete.
- 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 site to view and make changes, without affecting content stored on your internal server.
Before you continue, make sure the content you share is compatible between the internal (source) and external (destination) sites. The external site should be running the same version of Tableau as the internal site or later. For more information about compatibility, see Make Workbooks Compatible Between Versions in Tableau Desktop help.
Use the following steps to share content externally:
Work with the external site administrator to determine a user account that has publishing rights on the site. You will use this user account to create the migration plan. For more information, see Set Users’ Site Roles and Permissions.
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.
Create a plan and select the internal site as the source and the external site as the destination. For more information, see Create a Plan in Migration Plan Overview topic.
Select the content you want to share with the external site. You can select entire projects, specific workbooks and data sources and user permissions.
Verify and run the plan. When you are ready, click Run Migration to end the Planning phase 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 finalise your migration, but it cannot perform the actual database migration.
Use the following steps to validate database migrations:
Create a plan and select the Tableau site to use as your source. In this example, we describe a migration between projects on the same Tableau site, so select the same site for your destination. For more information, see Create a Plan in Migration Plan Overview topic.
- Configure the migration to copy your content to a new project. Let’s call the source project as Project A, and the new or the destination project as Project B.
Changes to workbooks: Create a workbook mapping to change Project A to Project B. For a full list of workbook transformations, see Migration Plans: Workbooks.
Changes to data sources: Create a data source mapping to change the Project A to Project B. For a full list of data source transformations, see Migration Plans: Published Data Sources.
Verify and run the plan. When you are ready, click Run Migration to end the Planning phase and prepare to run your plan.
Update the content in Project B with the new database connections or replace the data sources. This needs to be done manually by authoring.
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.
Once you have confirmed everything is working as expected, overwrite the content in Project A with the updated content in Project B.
Note: If the content already exists in the destination project and you do not select the Overwrite Newer Workbooks and Overwrite Newer Data Sources publish options, the content will not be copied to the destination project.
Geographical content migration
If you are maintaining a geographically distributed, multi-site environment, you will need some of this content to be shared and accessible across all the servers. This use case describes how to migrate content between servers in different geographies. The server can be in the same country or across continents.
Best Practices:
- We recommend prioritising the content that you most need. Content Migration Tool shouldn't be used to copy entire server environments to multiple geographies.
- We recommend migrating content in one direction only meaning Primary to Secondary. Here we use the term Primary to indicate the source site and Secondary to indicate the destination. You can have one or more destination by creating multiple migration plans.
Use the following steps to migrate between Tableau Server that are distributed in different geographies:
Create a plan and select the Primary site as the source and the secondary site as the destination. For more information, see Create a Plan in Migration Plan Overview topic.
Select content that you want to share between the Primary and Secondary.
Verify and run the plan. When you are ready, click Run Migration to end the Planning phase and prepare to run your plan.
To schedule this to run regularly, 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.
Review the content on the source periodically to determine if new items should be added to the migration plan.
Consolidate sites
If you need to combine the content of multiple sites into a single site (if, for example, organisational restructuring has changed how your sites should be arranged), you can use the Content Migration Tool to do this.
Note: Before consolidating sites, make sure you understand the limitations when migrating content using the Content Migration Tool. For more information, see Migration Limitations.
Use the following steps to copy all the workbooks and data sources from one site to another:
Create a plan and select the site you want to consolidate as the source. For more information, see Create a Plan in Migration Plan Overview topic.
On the Source Projects page, select All Projects and click Next.
If a project with the same name exists on the destination site, the content will be migrated to the same folder.
On the Project Options page, select your preferences for the destination site and click Next.
If the content already exists in the destination project and you do not select the overwrite option, the content will not be copied to the destination project.
On the Workbook Selection screen, select All Workbooks.
(Optional) If you are copying published data sources:
From the left navigation menu, under Published Data Sources, click Selection.
Select All Data Sources.
Click Run Migration and review the migration plan. When you’re ready, click Run at the bottom of the screen to run the migration.
Repeat these steps until you’ve consolidated all sites. For more information, see Planning in Migration Plan Overview topic.
Maintenance tasks
You can use the Content Migration Tool to perform a variety of maintenance tasks.
Tagging stale content
Using the 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:
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.
Select the content you want to restore from the backup Tableau Server.
Verify and run the plan. When you are ready, click Run Migration to end the Planning phase and prepare to run your plan.
Review the content on the production server.
Partial backup
Once you have a backup Tableau Server environment, you can use the Content Migration Tool to transfer new content from production to the backup Tableau Server. If you have not configured a backup Tableau Server environment, see the Disaster Recovery for Tableau Server whitepaper for more information.
Notes:
- 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.
- The Content Migration Tool shouldn't be used to perform your first backup.
Use the following steps to perform a partial backup of your content:
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.
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.
Verify and run the plan. When you are ready, click Run Migration to end the Planning phase and prepare to run your plan.
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.