Migration Plans: Permissions and Ownership
The Content Migration Tool allows you to replicate workbook and data source permissions to Tableau environments in different network domains or have differences in username or group syntax. You can create user permissions mappings to customise and secure content after it has been published to the destination location. Mappings are applied if Copy Project Permissions, Copy Workbook Permissions, or Copy Data Source Permissions have been selected earlier in the planning phase, along with Apply User Mappings.
For more information, see Migration Plans: Source Projects, Migration Plans: Workbooks and Migration Plans: Published Data Sources.
Mapping limitations
Content Migration Tool will stop the migration process if it fails to find the mapped user or group in the destination location. Subsequent user or group permissions mappings are not checked after the first failure, and the plan must be run again.
Content Migration Tool cannot replicate permissions if the source content has permissions for multiple users and groups with identical names. This only occurs when there are duplicate user or group names sourced from separate domains.
Step 1: Add mapping
To add user permissions mapping, click Add Mapping and select whether to change the name of a domain, user or group, or to import mappings from a comma-separated values (CSV) file. If Content Migration Tool is unable to match a permission in the destination location, the source content will not be migrated.
Domain Mapping
Domain permissions mapping applies to all users and groups in the destination location. If you are unsure about the source or destination domain, you can check the user and group pages on your Tableau site. If local user provisioning has been selected, the domain must be specified as local.
User Mapping
User permissions mapping automatically populates a list of users from the source and destination locations using the syntax domain\user. You cannot enter and save the names of users that don’t exist.
Note: When migrating between projects on the same site, the destination location and list of users will be the same. You can use mappings to update content ownership from User_A to User_B on the site.
Group Mapping
Group permissions mapping automatically populates a list of users from the source and destination locations using the syntax domain\group. You cannot enter and save the names of groups that don’t exist.
Import mappings from a CSV file
Starting in version 2021.4, you can import a CSV file containing domain, user and group mappings to quickly prepare your data for migration. Importing mappings can reduce the manual steps required to run a migration plan by allowing you to create and edit your mappings in bulk outside of Content Migration Tool. To import mappings, select Import from File from the Add Mapping menu.
CSV file format requirements
When you create a CSV file to import mappings, make sure that the file meets the following requirements:
The file does not include column headings. Tableau assumes that every line represents a mapping.
The file contains three comma-separated values per row: mapping type, source domain/user/group and destination domain/user/group.
Include the domain for usernames and groups if the server uses Active Directory authentication or "local" if a local identity store is used.
You must specify "domain", "user" or "group" for mapping type, as shown in the following table. The source and destination columns provide example syntax for Active Directory and a local identity store. Actual values in the CSV file will vary depending on your organisation.
| Mapping Type | Source | Destination |
| domain | <domain> | <domain> |
| user | <domain>\<user name>local\ <user name> | <domain>\<user name>local\ <user name> |
| group | <domain>\<group name>local\ <group name> | <domain>\<group name>local\ <group name> |
Import user permissions mappings
To import user permissions mappings in the Content Migration Tool:
Click Add Mapping and select Import from File.
In the dialog window, click Export CSV to export a .csv file containing all users and groups from the source site. Edit the resulting file in a text editor to add mappings for the destination site.
If you already have a mapping file, skip to step 3.
Note: The exported CSV file doesn’t include domains from the source site. Domains must be added manually to the CSV to create domain mappings.
Click Import Mappings and select the mapping file you want to import.
Content Migration Tool will validate the mappings for errors when importing the file. If errors are detected, you must fix each error in the CSV file and then import it again.
CSV import example
The following example shows a CSV file that contains multiple mapping types.
user,local\hwilson,companyx.lan\henry.wilson user,local\jjohnson,companyx.lan\janna.johnson user,local\mkim,companyx.lan\michele.kim user,local\fsuzuki,companyx.lan\fred.suzuki user,local\awang,companyx.lan\alan.wang user,local\snguyen,companyx.lan\susan.nguyen user,local\lrodriguez,companyx.lan\laura.rodriguez user,local\agarcia,companyx.lan\ashley.garcia group,local\All Users,companyx.lan\All Users group,local\Finance Team,companyx.lan\Finance Group domain,dev.mycompany,prod.mycompany
A preview window is displayed while importing the CSV that shows mappings removed, added or updated, unchanged and ignored. Review that the mapping changes are correct and click Accept.
Once the mappings are imported successfully, you can edit, delete or change the mapping order as described in Step 2.
Step 2: Change mapping order
After a permissions mapping is created, you can change the order using the Up or Down options to determine when it will be handled during the migration. When a domain, user, or group is handled in a permissions mapping, any subsequent permissions mappings for the source domain, user or group will be ignored.
In the example below, permissions for User_A are mapped to User_B. Content Migration Tool will ignore the second permissions mapping because User_A has already been handled.
In the example below, the first permissions mapping associates the domain for all users to prod. Content Migration Tool will ignore the second permissions mapping because the domain for User_A has already been handled.
Step 3: Continue to next step
When you are ready, click Next to continue to the Migration Plans: Migration Scripts 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.