CSV Import File Guidelines


You can automate adding 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 licence level and the publishing access, to apply to the users at the same time you import them.

To import users, you can use the server or site administration pages or the tabcmd utility. Using tabcmd provides an option for assigning a site role to all users in the CSV file. For information, see Import Users or createsiteusers filename.csv.

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 when configured with or without identity pools(Link opens in a new window).

CSV file format requirements

When you create the CSV file for importing users, make sure that the file meets the following formatting requirements:

  • The file does not include column headings. Tableau Server assumes that every line in the file represents a user.

  • The file is in UTF-8 format, and includes the byte-order mark (BOM).

  • Character encodings such as BIG-5 have been converted to UTF-8. You can do this by opening the file in a text editor and using the Save As command.

  • If a username includes an @ character that represents anything other than a domain separator, you need to refer to the symbol using the hexadecimal format: \0x40

    For example, user@fremont@mycompany.com should be user\0x40fremont@mycompany.com

Required columns in the CSV file

The following fields are required for each user:

  • Username. The username. If the server is configured to use Active Directory, this value must match a user defined in Active Directory. If the username is not unique across domains, you must include the domain as part of the username (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. A password for the user.

    • If the server is configured to use Active Directory, this value is not used. However, there must be a password column, and the column itself should be empty.

    • If the server is using local authentication, you must provide passwords for new users.

    Note: Enforcement of the required password field started in Tableau Server 2024.2. For more information, see the Unexpected “errorCode=134” occurs when attempting to add users via tabcmd in Tableau Server 2024.2 knowledge article.

Additional import file options

The CSV file can contain the following fields in addition to the fields listed above, in the order shown here:

  • Display name. The display name is part of the information used to identify a user on the server. If the user’s display name is already in use, Tableau Server updates the existing user information with the settings in the CSV file. If the server is configured using Active Directory, this value is not used.

  • Licence level. This can be Creator, Explorer, Viewer or Unlicensed. If you specify Creator for a particular user account, then you must also set the Publishing capability to True.

  • Administrator level (System, Site, or None). This setting determines whether the user is imported as an administrator.

    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 (yes/true/1 or no/false/0). If you are using the web UI, the publisher setting is used only if you import while signed in to a specific site.

  • 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.

If adding users to an identity pool, the following values are needed in addition to the above:

  • Identity pool name. The name of the identity pool that you want to add the user to.

  • 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. Note: The identifier is required if adding a user to an identity pool that uses Active Directory (or LDAP) identity store. The identifier is optional if adding a user to an identity pool that uses the local identity store.

    Notes:

    • 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.

    • For the username value, 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.

    • 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.

Important: The order of the columns is significant. The first column is treated as the username, 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.

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.

Notes

  • 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.

  • If you have a user-based server installation, and if adding users would exceed the number of users allowed by your licence, the users are added as unlicensed users.

  • If you use tabcmd and specify the licence, but importing users would exceed your licence limits, users are imported as Unlicensed.

CSV settings and site roles

The licence level, administrator, and publishing settings for a user determine how the user's site role is set during the import process. The following table shows how the settings are converted to site roles.

CSV settingsSite role

Licence level=(any)

Administrator=System

Publisher=true

Server Administrator. This setting applies to Tableau Server only, and it is valid only if you are importing users while managing the server (that is, not signed in to a specific site).

The Server Administrator site role always takes a Creator licence if one is available. If no Creator licence is available, see Troubleshoot Licensing to learn about the way Tableau Server handles this.

Licence level=Creator or Explorer

Administrator=Site

Publisher=true

Site Administrator Creator or Site Administrator Explorer. This setting is valid only if you are importing users while signed in to a specific site.

Licence level=Creator

Administrator=None

Publisher=true

Creator

Licence level=Explorer

Administrator=None

Publisher=true

Explorer (Can Publish)

Licence level=Explorer

Administrator=None

Publisher=false

Explorer

Licence level=Viewer

Administrator=None

Publisher=false

Viewer

Licence level=Unlicensed

Administrator=None

Publisher=false

Unlicensed

CSV import examples for Tableau Server

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 give 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

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
Back to top
Thanks for your feedback!Your feedback has been successfully submitted. Thank you!