Migration Plans: Workbooks

You have successfully signed into both your source server and your destination server, selected projects, and chosen sites where your workbooks reside and where you want them migrated. 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 Migrating Workbooks and Data Sources that use Extracts.

Step 1: Workbook Selection

All of the workbooks in the source site and 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. Alternately, 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, mousing 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, mousing 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 allow 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.

Again, using the All Workbooks radio button is different than selected 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, as well.

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, then the selected workbooks will simply be migrated with the same name and into the same project as the source. If you have not defined in projects in your destination site, then 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

To rename the workbook(s) that are being migrated, this transformation will allow you to filter by project in the Source site and provide a drop-down list to select the desired workbook. In the Destination field, select which project you would like the workbook to be directed as well as entering the desired new 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 Tableau Server and create the project manually. You can create projects and nested project 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 customize 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 have 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 check 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 any images in the selected workbooks. On the options tab, enter the file name of the old image and file name of the replacement image. You can use a local file path or URL to replace images.

Example:

File Name: C:\file\image.png

Replacement Image URL: http://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 customize 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 have 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 options tab, enter in the file path for the new data source.

Set Custom SQL

On the options tab, enter in any custom SQL in the text area desired. 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

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 in Tableau Server or Tableau Online. 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 checked, 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.

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: User Permissions Mapping.

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.

Note: The list of schedules generated are from the destination.

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 Next Step

You have completed the workbooks section of the planning phase of your migration. Click Next to continue.

You will now move on to the Migration Plans: Published Data Sources section of the planning phase.

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!