Prepare for the Upgrade - Pre-tsm (Windows)

To properly prepare to upgrade from Tableau Server on Windows 2018.1 or earlier to version 2018.2 or later, gather the following information about your existing installation, key files related to your installation and the upgrade, and complete the pre-upgrade tasks.

Gather custom configuration information

If you are upgrading on the existing hardware your configuration will be preserved, but it's a good practice to collect this configuration information about your existing installation for several reasons: you need this information when you configure a test environment, you need this information if you are migrating to new hardware migration as part of the upgrade, and you can use the information to confirm that the upgraded Tableau Server is configured as expected if you notice something unexpected after upgrading.

Collect this information and any associated files and save them to a location that is not on any of the Tableau Server computers.

The following list includes examples of the type of information you should gather:

  • Customizations This includes non-default ports, timeout values, custom logo images, and fonts.

    Also make a note of Windows path environment variables that affect Tableau Server.

  • SMTP configuration.

    For pre-TSM versions of Tableau Server (versions 2018.1 or earlier), you can see your current SMTP configuration on the SMTP Setup tab of the Configuration utility. For more information, see config_smtp.htm(Link opens in a new window).

  • SSL configuration and certificates.

    For pre-TSM versions of Tableau Server (versions 2018.1 or earlier), you can see your SSL configuration on the SSL tab of the Configuration utility. This tab also lists the location of the certificate and certificate key files. You should copy and save these files in a safe location. For more information, see Configure External SSL(Link opens in a new window).

  • SAML configuration, certificates and any IdP metadata files.

    For pre-TSM versions of Tableau Server (versions 2018.1 or earlier), you can view your current SAML configuration on the SAML tab of the Configuration utility, including the certificate, key, and metadata files. Save copies of these files to a safe location. For more information, see Configure Server-Wide SAML(Link opens in a new window).

  • Kerberos configuration.

    For pre-TSM versions of Tableau Server (versions 2018.1 or earlier), you can see your current Kerberos configuration on the Kerberos tab of the Configuration utility, including the location of the keytab file you should copy and save. For more information, see Configure Kerberos(Link opens in a new window).

  • OpenID configuration.

    For pre-TSM versions of Tableau Server (versions 2018.1 or earlier), you can find your current OpenID configuration details on the OpenID tab of the Configuration utility. For more information, see Configure Tableau Server for OpenID(Link opens in a new window).

  • Additional node configurations. Collect the configurations of any additional Tableau Server nodes, including any certificates or other supporting files that you copied to these nodes.

    For pre-TSM versions of Tableau Server (versions 2018.1 or earlier), you can find detailed information about the number of processes configured on each node on the Servers tab of the Configuration utility.

  • Other values. Note the number of projects, groups, workbooks, views, data sources, and users you have in your production environment. Having this information makes it easy to do a quick check after the upgrade to make sure everything was restored as expected.

Gather the environment configuration

The steps you need to take during the upgrade process depend on whether you're installing the upgrade on the same hardware or you're migrating to new hardware. Upgrading on the same hardware is straightforward and requires a minimum of manual steps (the steps you need to take depend on what version you are upgrading from, what version you are migrating to, and whether or not your existing installation is in the default location). Migrating to new hardware requires you to manually restore your Tableau Server data and reconfigure your settings after you install the new version.

Copy the setup files to a local file share

You will need the following setup files before you upgrade Tableau Server:

  • The Setup program for your existing version of Tableau Server.

    You might not need the Setup program. However, we recommend that you have it available in case there's a problem during the upgrade. That way you can use the setup program and your server backup to restore your installation to its pre-upgrade state.

    Note: If you do not have the Setup program for your existing version, you can download it from the Alternate Downloads Site(Link opens in a new window). Save the Setup program in a safe location that is not part of your production or test version of Tableau Server. You will need the Setup program if you need to go back to your existing version after upgrading.

  • The setup program for the new version of Tableau Server.

Update tabcmd

A new version of tabcmd is released with every release of Tableau Server. If you install tabcmd on computers that are not part of your Tableau Server installation, you need to update tabcmd on those computers as part of your upgrade process. For more information, see tabcmd.

Back up Tableau Server data

Make a backup of your installation of Tableau Server before beginning the upgrade process, and save the backup file to a safe location (a network share for example). Do not save it on any computer that is part of the Tableau Server installation. This backup provides data that you'll need to set up a test version of the upgraded environment. It also lets you recover if the upgrade process fails.


  • We recommend you disable subscriptions and scheduling in your production environment immediately before taking the backup, and reenable them after the backup is complete. Doing this will help avoid having your users receive duplicate subscriptions and email messages when you restore your backup in your test environment.

  • The full backup can take a while if you have a large installation or a lot of extracts.

  • Any changes made between the time you took the backup and the time you do the upgrade are lost because they aren't included in the backup.

  • You can only restore from a backup that has the same type of identity store as the running server. For example, a backup from a server using local authentication can be restored to a Tableau Server initialized with local authentication, but a backup from a server using Active Directory authentication cannot be restored to a server initialized with local authentication.

For more information, see Remove Unneeded Files(Link opens in a new window) and Back Up Tableau Server Data(Link opens in a new window).

Save your asset keys file before uninstalling Tableau Server for Windows 2018.1.x or earlier

If you are upgrading from Tableau Server on Windows version 2018.1.x or earlier, and you generated a custom asset key, save a copy of the asset_keys.yml file before you uninstall your earlier version. Store this file in a safe place that is not part of your Tableau Server installation (a network share for example).

In most cases you will not need this file. The upgrade process updates asset keys automatically when an upgrade is successful. You only need this file if the upgrade fails and you need to install a new version of Tableau Server and manually restore your backup file. In this case, you also need to specify the asset keys file when doing the restore.

Locating an existing asset keys file

If you generated a custom asset key file, you will have an asset_keys.yml file in the data directory. By default this is:

\ProgramData\Tableau\Tableau Server\data\tabsvc\config

If you do not see an asset_keys.yml file, you can skip this.

Restoring a pre-2018.2 Tableau Server for Windows backup and specifying an asset keys file

To manually restore a backup from Tableau Server 2018.1.x on Windows or earlier to Tableau Server 2018.2 or later, and include asset keys, use tsm, for example:

tsm maintenance restore --file <backup> --ak <asset_key_file>

For more information, see tsm maintenance restore.

Check your product maintenance status

If you attempt to upgrade a Tableau Server installation that has a product key with expired maintenance, your upgraded Tableau Server will be unlicensed and the upgrade may fail. Before upgrading, make sure that the server's maintenance hasn't expired.

If your maintenance has expired, select the product key and then click Refresh. If this does not update the maintenance date, check the Tableau Customer Portal for a replacement Tableau Server product key with a later maintenance date. For any questions or concerns, please contact Tableau Technical Support(Link opens in a new window). Reactivating the product key will be part of the upgrade process.

For more information, see Activate and Register Tableau Server. If your server doesn’t have internet access, see Activate Tableau Server Offline - Adding a License.

Important: If you are upgrading from Tableau Server version 2018.1 or earlier, make sure the Manage Product Keys application is closed before you uninstall Tableau. Leaving it open may result in a failed upgrade.

Disable your extract refreshes

Beginning in 10.5, extracts use .hyper format instead of .tde. Once the file format has been upgraded to .hyper, it cannot be reverted back to .tde format and cannot be opened in Tableau Desktop version earlier than 10.5. For more information, see Extract Upgrade to .hyper Format.

The following tasks on Tableau Server will upgrade a .tde extract to a .hyper extract:

  • Manual refresh

  • A scheduled full or incremental extract refresh

  • Automated refresh tasks that are performed through tabcmd, Extract API 2.0, or through Extract Command Line Utility

  • Automated append data to an extract using tabcmd or using the Extract Command Line Utility

Note: We recommend that you disable any automated tasks and schedules that result in an extract upgrade. If you have desktop versions that have not yet been upgraded to 10.5, your desktop users will not be able to open the upgraded .hyper extracts. You may also want to first test a few extracts manually after doing the server upgrade, and then reenable any schedules or automated refresh tasks.

For more information about extract refresh scheduling, see Enable Extract Refresh Scheduling and Failure Notification.

Ensure that your license has enough user capacity

When upgrading from a Tableau 2018.1 or earlier license with legacy site roles, all users are automatically mapped to their current equivalent site role. Before upgrading, it’s important to make sure that your new license supports the number of users you have. Otherwise, some users may become unlicensed after the upgrade.

The following table shows the mapping of the legacy site roles to the current site roles.

2018.1 legacy site role 2018.1 user-based site role 2018.2 and later site role
Server Administrator Server Administrator Server Administrator
Site Administrator Site Administrator Explorer Site Administrator Explorer
Publisher Explorer (can publish) Explorer (can publish)
Interactor Explorer Explorer
Viewer Read Only Viewer

Users always use the highest level role they have on any site, which is called the Maximum Site Role. You can view the Maximum Site Role is for users before you convert your license. For more information, see Permissions.

If you have more users than licenses for your current roles, you should reallocate or balance users to the available roles by changing their role, unlicensing users, or moving users. You can use the following steps to synchronize groups of new users after upgrading to 2018.2 or later:

  1. Unlicense all users.

  2. Create five Active Directory (AD) groups (one for each site role).

  3. Import users into the correct AD group for the appropriate site role, and then sync those groups with Tableau Server. For more information, see Create Groups via Active Directory.

  4. Restart Tableau Server. Users are automatically migrated into their new site roles. Content permissions are not affected.

Plan your strategy if you use virtual machines (VMs)

If you run Tableau Server on VMs, either locally, or in the cloud, be aware of the potential for complications related to licensing. If you are simply upgrading Tableau Server on the VM, you do not need to take any extra action related to licensing. If you plan to clone the VM to create either a new production or test environment to upgrade, you need to deactivate any Tableau Server licenses before cloning. If you do not do this, the new VM environment can end up with an untrusted license, and any attempts to upgrade will fail. You may also end up hitting the maximum number of activations for the licenses.

To avoid issues with licensing on VMs, deactivate all Tableau licenses before cloning a VM or allowing it to be permanently shut down.

To clone a VM, make sure Tableau is unlicensed (all licenses are deactivated) before cloning. After cloning the VM, activate a Tableau license there and proceed with the upgrade. If you have role-based licensing, be sure that the first license you activate is a Creator or Explorer license, or you may lose administrator access to your new Tableau installation.

Thanks for your feedback!