Was this page helpful?
Yes No

Export or Import a Site

Tableau Server on Windows now includes Tableau Services Manager (TSM), which replaces the Configuration Utility and the tabadmin command line tool. If you need help for an earlier version of Tableau Server, see the Tableau Help page.

You can provision a new Tableau Server site by importing (migrating) information from another site. You do this by exporting the existing site’s (the source site) information to a file. Then you complete steps to verify and import that information to the target site.

Site migration options

You can migrate a site in any of these ways:

  • To another site on the same Tableau Server instance.

  • To a site on a separate Tableau Server instance.

  • From Tableau Online to your Tableau Server deployment.

    Many of the tips listed in Prepare the source and target sites apply to the Tableau Online-to-Tableau Server migration. However, become familiar with What information is or isn’t preserved in a site export.

    Note: After you prepare your Tableau Online site for export, contact your Tableau representative. Tableau will complete the export steps, and your representative will send you the export files, which you can then import to your site on Tableau Server.

  • From Tableau Server on Windows to Tableau Server on Linux or vice-versa (or cross-platform Tableau Online-to-Tableau Server site migration).

What information is or isn’t preserved in a site export

The export file you create preserves workbooks, projects, data sources, and users. This includes permissions set on content, user favorites lists, site quota, and other site settings.

Users’ custom views are preserved; however, depending on the type of site migration, custom view URLs might change in a way that breaks users’ bookmarks to their views. For example, migrating from Tableau Online to a self-managed Tableau Server will change the host name and invalidate bookmarks.

In addition:

  • When you export a site on Tableau Server to import to another Tableau Server site, subscription and extract refreshes schedules are preserved.

  • When you export a Tableau Online site to import to Tableau Server, only the default schedules are preserved.

    On Tableau Online, users can create their own custom subscription schedules.

Usage data, which appears in the site’s administrative views, is not preserved. For example, view and data source counts, user actions, and performance data.

In addition, OAuth access tokens embedded in data connections are reset. For those data sources, you will need to edit the connections and re-authenticate to the underlying data.

Prepare the source and target sites

Before you export a site, complete the following checklist to prepare both environments. Some of these instructions depend on whether both sites are on the same server instance or on separate ones.

• Verify version compatibility
To import a site successfully, the source and target sites must be in the same product version family. For example, 2019.1 through 2019.1.x. You cannot import a site that is outside the target site’s version family. For example, 2018.3 to 2019.1. For version information, see the Tableau Release Notes.

• Identify node
The tsm sites commands will use your local file store to hold the export and import data. If you are running a multinode Tableau cluster, then you must run the tsm sites commands on a Tableau Server that is running the Data Engine process. For information about the Data Engine process and the processes that require it, see Tableau Server Processes.

• Delete stale content items
Make sure the source site contains only what you want to import to the new site. Delete unused workbooks, data sources, or projects.

• Remove obsolete users
Confirm that all server users are licensed, and remove accounts that are no longer in use. You can’t remove users during the import process, so if the two sites are on the same server instance, all users you export from the source site are imported to the target site.

• Create or identify the target site
You must import a site file to a site that already exists on the target Tableau Server instance. Because the import process removes anything from the target site that is not included in the import file, we recommend that you import to an empty site. For more information, see Add or Edit Sites.

Notes

  • If the target site is not empty, workbooks and data sources with names that are identical on both target and source sites are replaced. This can be verified by the time stamp.

  • If your source site has workbooks that use published data sources, the data connections in these workbooks continue to refer to the source site name. To maintain those connections without having to republish the workbooks, make sure the target and source site names match.

• Locate site IDs
The tsm command you use to export or import a site requires a parameter that takes the site ID. You can get the site ID from the URL when you’re signed in to the site from a web browser.

If only one site exists on the server, that site is named Default. When you’re signed in to the Default site, the browser URL looks something like this:

https://server-name/#/projects

In the URL, the absence of the /site parameter indicates that it’s the Default site. The site ID for the Default site is "Default" without the quotation marks.

On a multi-site Tableau Server deployment, the browser URL includes #/site/ followed by the site ID. The following URL would appear if you navigate to the Views page on a site whose site ID is finance:

https://localhost/#/site/finance/views

• Check user authentication
You can export from and import to sites that do not use the same user authentication method, but you will need to modify the mapping files used for the import. This step is built into the import process and described in 3. Verify that site settings are mapped correctly.

• Create users on the target server if necessary
The site import process assigns users to the target site. If the source site is on Tableau Online or on a Tableau Server instance other than the target site, you must create users on the target server before you can perform the import. If the two sites are on the same Tableau Server instance, the target site has access to the existing users, and you can skip this step.

User names are stored differently in Tableau Online, so when you export a Tableau Online site, you must edit the user-specific mapping file as part of the verification steps.

• Configure the target server to deliver subscriptions
Subscriptions are imported, but you must configure the server to deliver them.

For more information, see Set Up a Server for Subscriptions.

• Check schedules
The Schedules page lists the existing schedules for extract refreshes and subscriptions.

For migrations from one Tableau Server site to another, refreshes and subscriptions assigned to default schedules on the source site are mapped to the same schedules on the target site.

If the source site has schedules that do not exist on the target site, and the target site is on another Tableau Server instance, you must create the schedules on the target site that you want the source schedules to map to. You can edit the mapping files to make sure this is done as you expect.

For migrations from Tableau Online to Tableau Server, custom subscription schedules that users create are not mapped. Before you contact Tableau to request your site export, remove these custom schedules.

To remove them, go to TasksSubscriptions, and select the check boxes for the custom subscriptions. Then, on the Actions menu, select Unsubscribe.

Unsubscribe users from schedules they created before you export a Tableau Online site

Tips for importing to a target with fewer users or schedules than the source site

When a target site has fewer users or schedules than the source site, many-to-one importing is not supported. How you can address this depends on whether the source and target sites are on the same Tableau Server instance.

Note: Subscription schedule information in this section does not apply to Tableau Online-to-Tableau Server site migration.

You can take any of the following approaches that apply to your situation:

  • Remove extra users or schedules from the source site before you export.

    This is the preferred option if the two sites are on the same server instance.

  • Add missing users or schedules to the target site before beginning the import.

    This is required if the target site is on another server instance.

  • Add the missing users or schedules to the target site in the middle of the import process and manually update the mapping files.

    This is an option only if the sites are on the same instance.

  • Manually map the users or schedules to different users and schedules in the target site during the import process.

    This is required if a user name differs between servers—for example, the exported user named adavis@company.com is defined on the target site as davisa.

1. Export a site

On the Tableau Server machine, type the following command:

tsm sites export --site-id <source-siteID> --file <filename>.

Tableau Server must be running when you use the export command. During the export process, Tableau Server locks the site you’re exporting.

For example, to export a site with site ID weather-data to the file export-file.zip, type the following:

tsm sites export --site-id weather-data --file export-file

By default, Tableau Server saves <export-file>.zip to C:\ProgramData\Tableau\Tableau Server\data\tabsvc\files\siteexports. For more information, see tsm File Paths.

2. Generate the import mapping files

To generate import files for the target site, you need the .zip file you created when you completed the steps in 1. Export a site.

  1. On the Tableau Server machine, copy the exported .zip file to the directory Tableau Server expects to find the files for importing. For example:

    C:\ProgramData\Tableau\Tableau Server\data\tabsvc\files\sitesimports

  2. Verify that the target site already exists on Tableau Server. The import process will not create a site. See the previous section, Prepare the source and target sites.

  3. Run the following command (Tableau Server must be running):

    tsm sites import --site-id <target-siteID> --file <export-file.zip>

    This command generates a set of .csv files that show how source site settings will map to the target site. In the steps described in the next section of this article, you confirm these mappings and adjust them where needed.

    By default these .csv files are generated to a mappings directory created under siteimports. For example:

    C:\ProgramData\Tableau\Tableau Server\data\tabsvc\files\sitesimports\working\import_<id>_<date-time>\mappings

    For more information, see tsm File Paths.

3. Verify that site settings are mapped correctly

The .csv files you generated in the previous section describe how the source site’s resources will be assigned to the target site when the import is complete. Items in the files that Tableau Server was unable to map, and that you need to edit, are indicated by a series of question marks (???). Before you can complete the import process, you must replace the question marks with valid assignments on the target site.

Important: Some requirements apply to mapping users, schedules, and published content resources, particularly when the source and target sites are on separate Tableau Server instances. For more information, see Prepare the source and target sites earlier in this article.

To verify mapping files

  1. Navigate to the directory that contains the .csv map files generated by the tsm sites import command. By default:

    C:\ProgramData\Tableau\Tableau Server\data\tabsvc\files\sitesimports\working\import_<id>_<date-time>\mappings

  2. Use your preferred text editor to open one of the .csv files in the mappings directory, and do the following.

    1. Confirm that the mappings are correct.

    2. If an entry shows a series of question marks (???), replace them with a valid value.

      For descriptions of the settings in each of these files, use the tables in Mapping file content reference later in this article.

    3. Save the changes and preserve the CSV file formatting.

    Repeat this process for the remaining .csv files.

4. Import the correctly mapped files to the target site

After you verify the site mappings in the .csv files, you can import the settings to the new site to complete the migration process.

  1. Run the following command:

    tsm sites import-verified --import-job-dir <import-id-directory> --site-id <target-siteID>

    For example:

    tsm sites import-verified --import-job-dir "C:\ProgramData\Tableau\Tableau Server\data\tabsvc\files\sitesimports\working\import_ff00_20180102022014457"
    --site-id new-site

  2. When the success message appears, sign in to the new site and confirm that everything was imported as you expected.

Note: The tsm sites import and tsm sites export commands can leave a site in a locked state if an error occurs. To unlock a site, use the tsm sites unlock command.

Mapping file content reference

The following tables list the columns in each of the mapping files created when you run the tsm site import command.

CSV file name: mappingsDomainMapperForGroups

Column title

Can it be edited?

Description

source_name

No

A user group name on the source site.

source_domain_name

No

The user authentication type on the source site: either local (for local authentication) or a domain name (for Active Directory).

target_domain_name

Yes*

The user authentication type on the target site: either local for local authentication, or a domain name (such as example.com or example.lan) for Active Directory.

*For the All Users group, keep the target_domain_name value set to local, even if your target server is configured for Active Directory user authentication. The All Users group is a special default user group that must exist on every Tableau Server.

CSV file name: mappingsScheduleMapper

Column title

Can it be edited?

Description

source_name

No

The names of custom and default extract or subscription schedules on the source site.

source_scheduled_action_type

No

The type of schedule, either Refresh Extract, for extract refreshes, or Subscriptions, for subscription deliveries on the source site.

target_name

Yes

The names of custom schedules on the target site. You can edit this value. For example, if the schedule is named Friday Update on the source site you can rename it Friday Refresh on the target site.

target_scheduled_action_type

No*

The type of schedule, either Refresh Extract, for extract refreshes, or Subscriptions, for subscription deliveries on the target site.

*In the rare case that you see question marks (???) in this column, replace them with either Refresh Extract or Subscriptions, to match the entry you see under source_scheduled_action_type.

CSV file name: mappingsSiteMapper

Column title

Can it be edited?

Description

source_url_namespace

No

The site ID of the source site.

target_url_namespace

No

The site ID of the target site.

CSV file name: mappingsSystemUserNameMapper

Column title

Can it be edited?

Description

source_name

No

The user name attribute of a user on the source site.

source_domain_name

No

The user authentication type on the source site: local, for local authentication, a domain name (such as example.com) for Active Directory, or external (for a Tableau Online site).

target_name

Yes

The user name attribute for users who will be assigned to the target site upon import.

Confirm that all the user names in the list exist on the target server, and replace question marks (???) with user names that exist on the target server.

You cannot create user names by adding rows to the CSV file. Similarly, you cannot remove user names by deleting rows.

You can edit a user name in the target_name column to be different from its source user name, as long as the user already exists on the target server with that name.

For example, a user can have a source_name value of agarcia@company.com and a target_name value of ashleygarcia@company.com.

You can map a user on the source site to only one user name on the target site.

target_domain_name

Yes

The user authentication type on the target site: either local, for Local Authentication, or a domain name (such as example.com) for Active Directory.

CSV file name: MappingsScheduleRecurrenceMapperWithAutoCreation

This file does not require updates.