CSV Import File Guidelines

You can bulk add users by creating a comma-separated values (CSV) file with user information and then importing the file. You can include attributes in the CSV file, such as license level and the publishing access, to apply to the users at the same time you import them.

This topic covers the details of the CSV file itself. To import users using the CSV, you can:

You can import users at the site or server level. If you import users to the server (not to a specific site), the users aren’t assigned to a site and are imported as Unlicensed.

Note: Unless otherwise noted, the guidelines specified in this topic apply to Tableau Server configured with or without identity pools(Link opens in a new window).

CSV file format requirements

The CSV file for importing users has the following formatting requirements:

  • No column headings. Tableau Server assumes that every line in the file represents a user.
  • UTF-8 format with the byte-order mark (BOM).  
    • Character encodings such as BIG-5 must beconverted to UTF-8. You can do this by opening the file in a text editor and using the Save As command.
    • If the @ character is present in the username field for anything other than a domain separator, it must be in hexadecimal format: \0x40. For example, user@fremont@mycompany.com should be user\0x40fremont@mycompany.com.

Required column structure in the CSV file

The file shouldn't contain a header row. Not all columns need to be filled out, but the required column structure must be preserved by including all the expected comma delimiters.

The column structure varies by product and by import tool. Make sure you're using the appropriate structure for your environment:

  • Tableau Cloud: username, password, display name, license level, administrator level, publishing capability, email address
  • Tableau Cloud with Tableau Cloud Manager (TCM): tenant or site URI, username, password, display name, license level, administrator level, publishing capability, email address, authentication type
  • Tableau Server: username, password, display name, license level, admin level, publishing capability, email address
  • Tableau Server using identity pools: username, password, display name, license level, admin level, publishing capability, email address, identity pool name, identifier

See the column details section below for more information on the possible values for each column.

Important: The order of the columns is significant. The first column is treated as the user name, the second as the password, the third as display name, and so on, regardless of the content in the columns. If you omit values for a field, you must still include the field’s comma delimiter.

Column Details for Tableau Server

Note: If you are not signed in to a specific site and are importing users at the server level, you can assign only the Server Administrator and Unlicensed site roles.

Column structure for the CSV file: username, password, display name, license level, admin level, publishing capability, email address

Column details: 

Username: Required. The name of the user.

  • If the server is configured to use Active Directory, this value must match a user defined in Active Directory. If the user name is not unique across domains, include the domain as part of the user name (for example, example\Adam or adam@example).
  • If adding users to an identity pool(Link opens in a new window), make sure of the following:
    • If adding a user to an identity pool that uses AD as its identity store, make sure to use the AD sAMAccountName value for user name.
    • If adding a user to an identity pool that uses LDAP as its identity store, make sure to use the LDAP username value for user name.

Password: The password for the user. If this column is required or not depends on the configuration of the server: 

Display name: The display name is part of the information used to identify a user on the server. If this column is used or not depends on the configuration of the server:

  • Local authentication: If the user’s display name is already in use, Tableau Server updates the existing user information with the settings in the CSV file.
  • Active Directory: Ignored. As a best practice, leave this column blank.

License level: This can be Creator, Explorer, Viewer, or Unlicensed.

  • If the license level is Creator, the publishing capability must be Yes/True/1
  • If you have a user-based server installation and adding users would exceed the number of users allowed by your license, the users are added as unlicensed users.
  • If you use tabcmd and specify the license but importing users would exceed your license limits, users are imported as unlicensed users.

Administrator level: This can be System, Site, or None and determines whether the user is imported as an administrator.

  • System = Server administrator, Site = Site administrator, None = not an administrator.
  • If you are not signed in to a specific site and are importing users at the server level, you can assign only the Server Administrator and Unlicensed.
  • If you are using the web UI to import users, you can set the administrator site role to System only if you import the file at the server (All Sites) level. If you are signed in to a specific site, and if the administrator column for a user in the CSV file is set to System, Tableau Server imports the user as a site administrator.

Publishing capability: This can be Yes/True/1 or No/False/0. If you are using the web UI, the publishing capability is used only if you import while signed in to a specific site.

  • If the license level is Creator, the publishing capability must be Yes/True/1
  • If the license level is Explorer, the publishing capability value is what distinguishes the site role between Explorer (can publish) and Explorer
  • If the license level is Viewer or Unlicensed, the user will not be able to publish regardless of the value of this column

Email address: The email address is part of the information used to identify a user on the server. If the email address is already in use, Tableau Server updates the existing user information with the settings in the CSV file.

Any columns left blank must still be delimited with commas to preserve the column structure.

Identity Pools

If adding users to an identity pool, the following columns are needed in addition to the standard columns:

Column structure for the CSV file: username, password, display name, license level, admin level, publishing capability, email address, identity pool name, identifier

Additional column details:

Identity pool name: The name of the identity pool that you want to add the user to. If you are adding users to an identity pool and you don't specify the identity pool name, users are added to the initial pool (TSM configured), which is the set of users who were provisioned in TSM during Tableau Server setup.

Identifier: The identifier for the user you want to add. Identifiers are only used for identity matching purposes. For more information, see Usernames and identifiers in Tableau.

  • Local authentication: Optional
  • Active Directory or LDAP: Required

Bulk add users with Identity Pools

You can use the CSV import process to:

  • Bulk add users to additional identity pools. Note: You cannot use the CSV import process to replace the identity pool that a user already belongs to with another identity pool. If you add an existing user with a different identity pool value, they will be added to that additional identity pool.
  • Bulk add identifiers for users who don’t already have them. Note: If you add a different identifier for a user in the same pool, it will not replace the existing identifier for that user. Instead, a new identifier record will be created for that user.

CSV import examples for Tableau Server

Tip: Remember, the structure is: username, password, display name, license level, admin level, publishing capability, email address.

The following example shows a CSV file that contains information for several users.

henryw,henrypassword,Henry Wilson,Creator,None,yes,henryw@example.com
freds,fredpassword,Fred Suzuki,Viewer,None,no,freds@example.com
alanw,alanpassword,Alan Wang,Explorer,Site,yes,alanw@example.com
michellek,michellepassword,Michelle Kim,Creator,System,yes,michellek@example.com
  • If you import this file while managing a site, four users are added to that site. The Administrator setting for user Michelle is System. However, because you are importing the users into a site, Tableau Server gives Michelle the Site Administrator Creator site role. Three of the users are allowed to publish.
  • If you import this file while managing the server, four users are added to the server, but they are not added to any site. Only one user is imported as a server administrator; the rest are set to Unlicensed.

Identity pools examples

Tip: Remember, the structure is: username, password, display name, license level, admin level, publishing capability, email address, identity pool name, identifier.

The following example shows a CSV file that contains information for two users added to an identity pool.

henryw,henrypassword,Henry Wilson,Viewer,None,yes,hwilson@myco.com,General Contractors,hwilson
freds,fredpassword,Fred Suzuki,Creator,None,no,fsuzuki@myco.com,General Contractors,fsuzuki

The following example shows a CSV file that contains information for two users added to an additional identity pool.

henryw,henrypassword,Henry Wilson,Viewer,None,yes,hwilson@myco.com,General Contractors 2,hwilson
freds,fredpassword,Fred Suzuki,Creator,None,no,fsuzuki@myco.com,General Contractors 2,fsuzuki

The following example shows a CSV file that contains information for two users without existing identifiers.

janes,janepassword,Jane Smith,Viewer,None,yes,jsmith@myco.com,General Contractors,jwang
laurar,laurapassword,Laura Rodriguez,Creator,None,no,lrodriguez@myco.com,General Contractors,jrodriguez

Improve performance for large CSV files passed through tabcmd

Note: These settings apply to Tableau Server version 2022.1 and earlier. The search and index service they affect was deprecated starting in version 2022.3 and retired (removed completely) in 2023.3.

A server administrator can enable server settings that help to improve performance for importing large CSV files through tabcmd commands. You can do this using the tsm configuration set command with the following options:

  • vizportal.csv_user_mgmt.index_site_users
  • vizportal.csv_user_mgmt.bulk_index_users
  • searchserver.index.bulk_query_user_groups

Essentially, these options index users after the CSV file is processed, instead of one-by-one as they are added to the server’s database. This reduces the number of calls to the database and the memory required to process the file. These tsm configuration set options apply to the tabcmd createsiteusers, deletesiteusers, addusers, and removeusers commands.

For descriptions for these settings, see tsm configuration set Options.

CSV settings and site roles

The license level, administrator, and publishing settings for a user determine how the user's site role is set during the import process. The following shows how site roles should be captured in the CSV.

Site Role License level Administrator level Publishing capability

Server Administrator

This role is valid only if you are importing users while managing the server (that is, not signed in to a specific site).

Any, but the Server Administrator site role always takes a Creator license if one is available. If no Creator license is available, see Troubleshoot Licensing to learn about the way Tableau Server handles this. System True

Site Administrator Creator or Site Administrator Explorer

These roles are valid only if you are importing users while signed in to a specific site.

Creator or Explorer Site True
Creator Creator None True
Explorer (can publish) Explorer None True
Explorer Explorer None False
Viewer Viewer None False
Unlicensed Unlicensed None False