Migration Plans: Workbooks
You have successfully signed in to your source and destination sites and selected projects. The next step is to prepare your workbooks for migration.
Note: If your workbooks or data sources include extracts, be sure you read and understand the information in Migrate Workbooks and Data Sources with Extracts.
Step 1: Workbook selection
All of the workbooks in the source site and selected projects appear on the Workbook Selection screen.
If you make any changes to the workbooks in the source site while on this step, you can click Refresh to update the workbook listings. There are several different ways to select these workbooks.
Specific Workbooks Selection
There are three buttons in the Specific section. Any choices from the Basic section will immediately include the specifically selected workbook in the migration plan. Alternatively, you can individually select specific workbooks by clicking on each one.
Select All
This button will select or clear selection of all the workbooks in the site. If additional workbooks are added to the site after the plan is saved, they will not be automatically added the next time the plan is used.
Display:
Thumbnails
The default view shows your workbooks in thumbnail previews to help you differentiate each of them. In this view, hovering over the thumbnail will show previews of the other worksheets and dashboards within that workbook.
List
The list view is a more succinct listing that also provides additional information, including Workbook Name, Project, Tableau Version and Last Modified.
Clicking on any of the column headers will sort the workbooks appropriately. Also, hovering over any of the workbooks will also provide a floating preview of the worksheets and dashboards within that workbook. List view is particularly useful if you have a large amount of workbooks in a site.
Rule Based Selection
You can use Rule Based selection to choose workbooks based on specific criteria. Rule-based options will create workbook selection criteria to be used when the migration plan is run. Be aware that selecting "all" in any of the Rule Based options is different than the Specific Workbooks selection. A rule-based "all" selection will always include all workbooks, so any newly added workbooks are included in future migrations.
The Rule Based radio button allows you to select workbooks by using the following options:
Workbooks in projects
This menu allows you to select workbooks from specific projects.
Workbooks tagged with
This menu allows you to select workbooks by their tags.
Workbooks published by
This menu allows you to select workbooks by their author.
With each option, you can select individually or multiple by clicking on the option next to each entry. All selected workbooks will appear in the Selection Description box.
All Workbooks Selection
The last option is to select the All Workbooks radio button, which selects all workbooks in all projects in the site.
Using the All Workbooks radio button is different to selecting all of the workbooks using the Specific Workbook method because it will use every workbook in the source site each time the migration plan is used in the future.
When you are satisfied with your workbook selections, click Next.
Step 2: Workbook mapping
You can now map your selected workbooks from the source file to the destination file. Mapping allows you to rename source workbooks as they are migrated and choose different destinations. You can also add mapping to change the project, prefix or suffix for the workbooks as well. Projects can be added to the Destination in this section as well.
If you make no changes here, the selected workbooks will simply be migrated with the same name and into the same project as the source. If you have not defined projects in your destination site, they will be migrated into the Default project. To add workbook mapping click the Add Mapping button. The following options will appear in the mapping area.
Rename Workbook
This transformation allows you to filter by the Source project and select the desired workbook(s) to rename. In the Destination field, select which project you would like the workbook to be directed to and enter the desired name.
Change Project
By default, the workbooks are migrated to the same project in the destination. This mapping allows you to change the destination project for all workbooks from a source project.
Add Project
When renaming the workbook or changing the project, the Add New option allows you to create a destination project without having to sign in to the destination site and create the project manually. You can create both projects and nested projects using the Add New dialog box.
Change Prefix
This allows you to remove or replace the prefix for workbooks from one or all source projects.
Change Suffix
Like the prefix mapping, you can remove or replace the suffix for workbooks from one or all source projects.
Step 3: Workbook transformations
You can change and modify your workbooks by using the Transformation step.
Transformations modify your workbooks in a specified manner. Additional transformations can be included via plug-ins or will be added in future versions of the application. Click on the Add Transformation drop-down menu to see the selection of Transformations currently available.
Selecting any of the transformations will bring up the Edit Transformation window, which will allow you to customise it to your selected workbooks. All transformations will be completed in the order that they are listed from top to bottom.
For all of the different types of transformations, there are two basic steps. The first step is to make your selection for the transformation. In this case, select the workbook(s) you want to transform. The selection area is similar to the Workbook Selection section of the Planning phase with all of the features of the Basic selection radio button: Select/Unselect All, Refresh, Thumbnail Display and List Display. At the top of the list, you can select Select All workbooks, which is an option to automatically select all workbooks for future transformations. You can also Refresh the workbook display window to reflect any changes or updates to the source site.
The second step is to use the options tab to enter the specific selections for whichever transformation you select.
Each of the workbook transformations has different values to be entered on the options tab, and the tab will have different names depending on the transformation you're editing:
Action URL Replacement
Replace part or all of an URL action inside of the workbook using this transformation. On the options tab, enter the text that should be matched and its replacement value.
Example:
URL: www.exampledev.com
Match: dev
Replacement: Prod
Result: www.exampleProd.com
Set Parameter Value
Define a new parameter. On the options tab, enter the name of the Parameter, the data type from the drop-down menu and the value.
Remove Images
Remove any images (such as a watermark) in the selected workbooks by entering in the file name on the options tab. There is an additional tick box to receive a warning during migration if no image is found.
Remove Tooltip Commands
Remove all of the tooltip commands from the selected workbooks. There are no additional options to define for this transformation.
Replace Images
Replace images embedded in the selected workbooks. On the options tab, enter the file name of the current image and the replacement image. You can replace images using a local file path or URL.
Example:
File Name: image.png
Replacement Image URL: https://www.exampledev.com/replacementImage.png
Zoom Control Visibility
Set the visibility mode from the drop-down menu: Automatic, Show on Hover, or Hide on the options tab.
Web Page URL Replacement
Replace part or all of a web page URL used on dashboards using this transformation. On the options tab, enter the text that should be matched and its replacement value.
Example:
URL: www.exampledev.com
Match: dev
Replacement: Prod
Result: www.exampleProd.com
Step 4: Data source transformations
The next step in planning your workbooks for your enterprise migration are your data source transformations. It is similar in function to the Workbook Transformations step. These are for data sources that are packaged within the workbooks. Published data sources are handled in a different step in the process.
Click on the Add Transformation drop-down menu and the following options will appear:
Selecting any of the data source transformations will bring up the Edit Transformation window, which will allow you to customise it to your selected data sources. All transformations will be completed in the order that they are listed from top to bottom.
For all of the different types of data source transformations, there are two basic steps. The first step is to enter in the match criteria for the desired data source. Depending on which connection type you select, more fields will appear on the Match Criteria tab.
Click on the Preview Source Connections to find any connections that match the criteria entered.
The second step is to use the options tab to enter the specific selections for whichever transformation you select.
Each of the data source transformations has different values to be entered on the options tab:
Set Calculation Formula
On the options tab, you can replace the calculation for a column.
Set Connection Info
On the New Connection Values tab, enter the authentication method and connection details for the new data source. Depending on which connection type you select, more fields will appear.
Change published data sources with CMT
As of version 2022.1, select the Tableau Server (Published Data Source) connection type to change the published data source for a workbook. This can reduce the manual steps required when migrating workbooks between Tableau environments, for example, promoting content from development to production.
To change the published data source, select a data source from the drop-down menu and enter the Tableau Username for authentication. The user must exist on the destination site and have the Connect capability for the published data source.
For file-based data sources, users will access the workbook and see data based on the permissions of the specified Tableau user.
For all other data sources, users are prompted for their own database credentials when the view or workbook loads.
If Tableau Username isn't specified, only users with the Connect capability can see data in the workbook.
Set Custom SQL
On the New Custom SQL tab, enter the name of the custom SQL query you want to modify for Match Query Name. The query name must match the custom SQL query name from the physical layer of the data source. If these names don't match, the transformation will fail. For more information about data modelling and the physical layer, see The Tableau Data Model.
After entering the query name, enter the desired Custom SQL in the text field. Be aware that custom SQL can negatively impact the performance of your workbooks if improperly used.
Remove Extract
There is no options tab for this transformation, simply enter in the Match Criteria information and the extract will be removed during migration.
In addition, on each of the transformations you can enter notes in the Comments section on the left-hand side of the Edit Transformation window.
Apply Saved Credentials
Deprecated in version 2022.3. Use the Set Connection Info data source transformation instead.
On the options tab, enter the Tableau Username and corresponding Saved Credentials Username for the data connection. You can only apply saved credentials for existing data connections on the Account Settings page of your Tableau site. For more information, see Manage Saved Credentials for Data Connections.
Step 5: Publish options
The final step in the Workbooks phase is to select publish options and create transformations for tags, extract refresh schedules and permissions.
Reset Dashboard Selections
This option deselects all objects on dashboards.
Overwrite Newer Workbooks
If ticked, a workbook will be migrated even if it will overwrite a workbook that has been created at the same time or more recently than the moved workbook
Copy Workbook Permissions
When selected, the migration tool will attempt to match source workbook permissions as closely as possible.
Copy Extract Refresh Schedules
When selected, the migration tool will attempt to set the destination workbook extract refresh schedule(s) to schedules matching the source’s name.
Note: Extract refresh schedules cannot be created in Tableau Cloud. This option is not available if the destination is a Tableau Cloud site. For more information, see Migration Limitations.
Copy Embedded Credentials for Workbooks
Copy the embedded credentials for data sources embedded in workbooks. Only available when migrating from Tableau Server to Tableau Cloud sites. For more information, see Migrate Workbooks and Data Sources with Embedded Credentials.
Note: CMT does not support embedded credential migration for OAuth connections. To migrate OAuth credentials to the destination site, use the Set Connection Info data source transformation.
Copy Workbook Owner
Copy workbook owner settings from the source location to assign the workbook owner. If unselected, the Content Migration Tool user is given ownership of the workbook in the destination location.
Apply User Mappings
Apply user mappings to assign content ownership. Select this option if there are differences in username syntax in the destination location. For more information, see Migration Plans: Permissions and Ownership.
Add Option
Click on the Add Option drop-down menu for the different types of transformations you can add:
For all of the different types of transformations, there are two basic steps. The first step is to make your selection for the transformation. In this case, select the workbook(s) you want to transform. The selection area is similar to the Workbook Selection section of the Planning phase with all of the features of the Basic selection radio button: Select/Unselect All, Refresh, Thumbnail Display and List Display. At the top of the list, you can select Select All workbooks, which is an option to automatically select all workbooks for future transformations. You can also Refresh the workbook display window to reflect any changes or updates to the source site.
The second step is to use the options tab to enter the specific selections for whichever transformation you select. Note: The options tab will have different names, depending on which transformation you are editing.
Add Tags
This allows you to add one or more tags to the workbook. If you hover your mouse over a previously entered tag, a blue “X” will appear to allow deletion.
Remove Tags
This allows you to add one or more tags to the workbook. If you hover your mouse over a previously entered tag, a blue “X” will appear to allow deletion. You can also choose to remove the tag from the source or destination workbooks.
Apply Extract Refresh Schedules
Here you can apply destination extract refresh schedules to migrated workbooks. The list of schedules generated are from the destination.
Note: Extract refresh schedules cannot be created in Tableau Cloud. This option is not available if the destination is a Tableau Cloud site. For more information, see Migration Limitations.
Set Permissions
This transformation is to edit the permissions for the selected workbooks. Enter in a Group or User and then click Add. Adjust the permissions as desired. The four different options are to Allow the permission, Deny the permission, Inherit or to keep the Source Value.
Set Generate Thumbnail As
This allows you to set the User or Group to be used for generating user-specific data in the workbook thumbnail after being migrated. Each option has a drop down to select the desired user or group.
Step 6: Continue to the next step
After selecting your workbooks and preferences, click Next to continue to the Migration Plans: Published Data Sources section of the planning phase.
Who can do this
Tableau site user with an Explorer role or higher. To migrate content, you must have View and Download/Save a Copy capabilities for workbooks on the source site and View and Publish capabilities for target projects on the destination site. For more information, see Permissions.