Tableau Server
Administrator Guide
Version 8.2; Last Updated in 2015
Copyright © 2015 Tableau Software, Incorporated and its licensors. All rights reserved.
This product is Client Software as defined in Tableau Software’s End User Software License
Agreement.
- 3 -
Before you install...Make sure the computer on which you’re installing Tableau Server meets the followingrequirements:
l Supported operating systems—Tableau Server is available in 32-bit and 64-bitversions. You can install Tableau Server onWindowsServer 2003 R2 SP2 or higher,WindowsServer 2008,WindowsServer 2008 R2,WindowsServer 2012,WindowsServer 2012 R2,Windows 7,Windows 8, or Windows 8.1. The 64-bit version of TableauServer on a 64-bit operating system is recommended. Youmay install Tableau Serveron virtual or physical platforms.
l Memory, cores, and disk space recommendations—Tableau Server systemrequirements vary based onmany factors. The following areminimumrecommendations based on the number of users on the server:
DeploymentType
# Server Users CPU RAM Free DiskSpace
Evaluation/Proof-of-concept (64-bitTableau Server)
1-2 4-core 8GB 1.5 GB
Evaluation/Proof-of-concept (32-bitTableau Server)
1-2 2-core 4GB 1.5 GB
Small <25 4-core 8GB 5GBMedium <100 8-core 32GB 50GBEnterprise >100 16-core 32GB or
more50GB or more
Theminimum requirements for running the 64-bit version of Tableau Server are 4 coresand 8GB of RAM.
l Administrative account—The account under which you install Tableau Server musthave permission to install software and services.
l Optional: Run As Account—ARun AsUser account for the Tableau Server serviceto run under is useful if you’re using NT Authentication with data sources or if you’replanning on doing SQL Server impersonation. For more information, seeRun As Useron page 298 andSQL Server Impersonation on page 307.
l IIS and port 80—Tableau Server's gateway listens on port 80, which is also used byInternet Information Services (IIS) by default. If you are installing Tableau Server on amachine that's also running IIS, you shouldmodify the Tableau's gateway port numberto avoid conflict with IIS. See TCP/IP Ports on page 313 andEdit the Default Portson page 315 for details.
- 4 -
Configuration InformationWhen you install and configure Tableau Server youmay be asked for the following information:
Option Description Your InformationServerAccount
The server must have a user account that the servicecan use. The default is the built-inWindowsNetworkService account. If you use a specific user accountyou’ll need the domain name, user name, and pass-word.
Username:
Password:
Domain:
Active Dir-ectory
Instead of using Tableau’s built-in user managementsystem, you can authenticate through Active Directory.If so, you’ll need the fully-qualified domain name.
Active DirectoryDomain:
Open port inWindowsfirewall
When selected Tableau Server will open the port usedfor http requests in theWindows Firewall software toallow other machines on your network to access theserver.
__ - Yes
__ - No
PortsBy default Tableau Server requires several TCP/IP ports to be available to the server. See thetopicTCP/IP Ports on page 313 for the full list, including which portsmust be available for allinstallations vs. distributed installations or failover-ready installations. The default ports can bechanged if there is a conflict. SeeEdit the Default Ports on page 315 to learn how.
DriversYoumay need to install additional database drivers. Download drivers fromwww.tableausoftware.com/support/drivers.
- 5 -
Install and ConfigureHere are themain steps you need to take to install and configure Tableau Server:
Run Server SetupAfter you download the Tableau Server installation file, follow the instructions below to installthe server.
1. Double-click the installation file.
2. Follow the on-screen instructions to complete Setup and install the application.
3. After the installation completes, click Next to open the Product KeyManager window.
If you need to support characters that are not the Latin-1 set, install theWindowsLanguage Packs viaControl Panel > Regional and Language Options. Thelanguage packswill need to be installed on the primary server aswell as anyworkermachines.
Activate TableauTableau Server requires at least one product key that both activates the server and specifiesthe number of license levels you can assign to users. You can access your product keys fromthe Tableau Customer Account Center. After installing and configuring the server, the productkeymanager automatically opens so you can enter your product key and register the product. If
- 6 -
you need to activate the product on a computer that is offline, seeActivate Tableau Offlinebelow.
1. Select Activate and paste in your product key:
2. Refer to the download help page on the web site for step-by-step instructions.
Activate Tableau OfflineIf you are working offline you can follow the steps below to complete offline activation.
1. When the product keymanager opens clickActivate the product.Paste your server product key into the corresponding text box and click Activate. Youcan get your product key from the Tableau Customer Portal..
2. When you are offline, activation will fail and you are given the option to save a file thatyou can use for offline activation. ClickSave.
3. Select a location for the file and clickSave. The file is saved asoffline.tlq.4. Back in Tableau clickExit to close the Activation dialog box.5. From a computer that has Internet access, open a web browser and visit the Product
Activations page on the Tableau website. Complete the instructions to submit youroffline.tlq file.
- 7 -
After you submit your offline.tlq file online, while your browser is still displaying theProduct Activations page, a file called activation.tlf is created, and Tableau promptsyou to save the file to your computer.
6. Save the activation.tlf file andmove it to the computer where you are installing TableauServer. If you have Tableau Desktop installed on the computer you can then double-click the new file to complete activation. If you do not have Tableau Desktop installedcontinue to step 7.
7. On the computer where you are installing Tableau Server, open a command prompt asan administrator and run the following command:cd "C:\Program Files\Tableau\Tableau Server\8.2\bin"
8. Next, type tabadmin activate --tlf <path>\activation.tlf, where<path> is the location of the response file you saved from the Product Activations page.For example:tabadmin activate --tlf \Desktop\activation.tlf
Keep the command prompt window open.
9. After the license is initialized, you are prompted to activate the product again. OnTableau Server, clickStart > All Programs > Tableau Server 8.2
10. Right-clickManage Product Keys and selectRun as Administrator.Even if you are logged into the Tableau Server computer as an administrator, you needto do this to avoid a potential registration error.
11. ClickActivate the product.12. Enter your product key again (the same one you entered in step 1).
13. Save the .tlq file.
14. From a computer that has Internet access, open a web browser and visit the ProductActivations page again on the Tableau website. Complete the instructions.
Tableau will again create a file called activation.tlf and prompt you to save it.15. Save the file andmove it to the computer where you are installing Tableau Server.
16. Back in the command prompt window on Tableau Server, type tabadmin activate--tlf <path>\activation.tlf, where <path> is the location of the secondresponse file you saved from the Product Activations page. For example:tabadmin activate --tlf \Desktop\activation.tlf
Tableau Server is now activated. If you need additional assistance, contact TableauCustomer Service.
Configure the ServerTheConfigure dialog displays during Setup. You can open it after Setup by selectingAllPrograms > Tableau Server 8.2 > Configure Tableau Server on theWindowsStart
- 8 -
menu. You need to stop the server beforemaking any configuration changes. SeeReconfigure the Server on page 22 for steps.There are two things to keep inmind about the settings you specify in the Configuration dialogbox::
l Settings are system-wide: The settings you enter apply to the entire server. If theserver is runningmultiple sites, these settings affect every site.
l User Authentication is "permanent": All of the settings can be changed after Setupby stopping the server and reconfiguring. The exception is theUser Authenticationsetting (General tab). It is "permanent" in the sense that changing fromUse LocalAuthentication toUse Active Directory requires you to uninstall, then reinstall theserver.
See the topics below for details on the different Configuration tabs:
GeneralUse the steps below to configure options on theGeneral tab:
1. By default, Tableau Server runs under the Network Service account. To use an accountthat will accommodate NT authentication with data sources, specify a user name andpassword. The user name should include the domain name. SeeRun As User on page298 to learnmore about using a specific user account.
2. Select whether to useActive Directory to authenticate users on the server. SelectUseLocal Authentication to create users and assign passwords using Tableau Server'sbuilt-in user management system. You cannot switch between Active Directory andLocal Authentication later.
3. If you use Active Directory:l You can optionallyEnable automatic logon, which usesMicrosoft SSPI toautomatically sign in your users based on their Windows username and
- 9 -
password. This creates an experience similar to single sign-on (SSO). Do notselectEnable automatic logon if you plan to configure Tableau Server forSAML, trusted authentication, or for a proxy server.
l Be sure to type the fully qualified domain name (FQDN) and nickname.
To determine the FQDN: SelectStart > Run then type sysdm.cpl in the Runtextbox. In the SystemProperties dialog box, select theComputer Name tab.The FQDN is shown near themiddle of the dialog box. The first time your userssign in, theywill need to use the fully qualified domain name (for example,myco.lan\jsmith). On subsequent sign-ins, they can use the nickname(myco\jsmith).
4. The default port for web access to Tableau Server (via HTTP) is port 80. Youmay needto change the port number if you have another server running on port 80 or othernetworking needs. For example, youmay have a hardware firewall or proxy in front ofthe Tableau Server host, whichmight make running a back-end system on port 80undesirable.
5. Select whether to open a port inWindows firewall. If you do not open this port, users onother machinesmay not be able to access the server.
6. Select whether to include sample data and users. The sample data can help you getfamiliar with Tableau Server, especially if you are installing a trial version of the product.Initially the sample user uses one interactor license. You can change this user tounlicensed in order to reclaim the license levels. See Licenses and User Rights onpage 82 to learn how. If you select to include the sample user, a single user is installed.The username and password are shown below:
Username PasswordTableau Software test
7. Optionally continue to the next page to configure Caching and Initial SQL options. If youdo not want to configure these options clickOK.
Domains
When you are using Active Directory authentication for the server you can view a list of thedomains that are being used and edit their domain names and nicknames. Youmay need to do
- 10 -
this, for example, to ensure that Tableau Server is using the correct nickname for SSPIauthentication, or the correct domain name.Modify Domain Names
Tomodify a domain name:
1. Select the Users link in the Administration area on the left side of the page.
2. Click the Domains link at the bottom of the list of users. The list of domains shows thenumber of users and groups that have been added to the server from each domain.
3. To display a list of users who are part of a domain, click the domain name.
4. Tomodify the domain name or nickname, click theEdit link, type a new, fully qualifieddomain name or a nickname, then clickModify.
You canmodify the nickname for any domain the server is using. In general, you canmodify the full domain name for any domain except the one that you used to sign in.However, if the user name that you are currently signed in with exists in both the currentdomain and the new domain you canmodify the full name for the current domain.
Data ConnectionsUse the options on the Data Connections tab to configure caching and specify how you want tohandle initial SQL statements from data sources.
Caching
Views published to Tableau Server are interactive and sometimes have a live connection to adatabase. As users interact with the views in a web browser, the data that is queried getsstored in a cache. Subsequent visits will pull the data from this cache if it is available. The DataConnections tab is where you configure aspects of caching that will apply to all dataconnections:
- 11 -
To configure caching, select from one of the following options: :
l Refresh Less Often—Data is cached and reused whenever it is available regardless ofwhen it was added to the cache. This optionminimizes the number of queries sent to thedatabase. Select this option when data is not changing frequently. Refreshing less oftenmay improve performance.
l Balanced—Data is removed from the cache after a specified number of minutes. If thedata has been added to the cache within the specified time range the cached data will beused, otherwise new data will be queried from the database.
l Refresh More Often—The database is queried each time the page is loaded. The datais still cached and will be reused until the user reloads the page. This option will ensureusers see themost up to date data; however, it may decrease performance.
Regardless of how caching is configured, the user can click theRefresh Databutton on the toolbar to force the server to send a query and retrieve new data.
Initial SQL
For views that connect to Teradata data sources, workbook creators can specify a SQLcommand that will run once, when the workbook is loaded in the browser. This is called an
- 12 -
initial SQL statement. For performance or security reasons, some administratorsmaywant todisable this functionality. TheData Connections tab is where you do this:
To disable initial SQL functionality, select the Ignore initial SQL statements for all datasources checkbox.Workbooks created with initial SQL statements will still open but the initialSQL commandswill not be sent.
Alerts and SubscriptionsTableau Server can send you an alert by email if there's a system failure and it can emailsubscriptions to Tableau Server users, which are snapshots of their favorite views. TheAlertsand Subscriptions tab is where you specify the SMTP server that Tableau Server uses forsending email.
For both alerts and subscriptions, encrypted SMTP connections are not supported.
Configure Email Alerts
When you configure alerts, Tableau Server sends an email to the recipients under Send emailto any time the data engine, repository, or gateway server processes stop or restart, or anytime the primary Tableau Server stops or restarts. If you are running a single-server installation
- 13 -
(all processes on the samemachine), health alerts are only sent when Tableau Server is up.No DOWN alerts are sent. If you are running a distributed installation that's configured forfailover (seeConfigure for Failover and Multiple Gateways on page 50) a DOWN alertmeans that the active repository or data engine instance has failed and the subsequentUP alert means that the standby instance of that process has taken over and is now active.
To configure an email alert:
1. SelectSend email alerts for server health issues.
2. Under SMTP Server, enter the name of your SMTP server. Enter aUsername andPassword for your SMTP server account only if it requires one (some do, some do not).The default SMTP port value is 25. Under Send email from, enter the email addressthat will send an alert if there's a system failure. While the email address you enter musthave valid syntax (for example, [email protected] or noreply@myco), it does not haveto also be an actual email account on Tableau Server.
Keep theEnable TLS check box cleared so that the connection to your mail server isunencrypted.
3. Under Send email to enter at least one email address that will receive the alerts. If youenter multiple email addresses, separate themwith commas (not semicolons).
4. ClickOK. When you start the server it will trigger an email alert and this will confirm thatyou have set up alerts correctly.
Configure Email Subscriptions
To set up an SMTP server for sending subscriptions:
- 14 -
1. SelectEnable email subscriptions.
2. Under SMTP Server, enter the name of your SMTP server. Enter aUsername andPassword for your SMTP server account only if it requires one (some do, some do not).The default SMTP port value is 25. Under Send email from, enter the email addressthat will send subscriptions to Tableau Server users.
While the email address you enter must have valid syntax (as in <text>@<text>, suchas [email protected] or noreply@myco), Tableau Server does not require itto be an actual email account (however, some SMTP serversmay require it to be anactual email account). You can also override this system-wideSend email fromaddress on a per-site basis for subscriptions. SeeAdd or Edit Sites on page 116 fordetails.
Keep theEnable TLS check box cleared so that the connection to your mail server isunencrypted.
3. Under Tableau Server URL, enter http:// or https://, followed by the name ofthe Tableau Server. This namewill be used for the footer of subscription emails.
4. ClickOK.
SSLYou can configure Tableau Server to use Secure Sockets Layer (SSL) encryptedcommunications on all HTTP traffic. Setting up SSL ensures that access to Tableau Server issecure and that sensitive information passed between the web browser and the server or
- 15 -
Tableau Desktop and the server is protected. Steps on how to configure the server for SSL aredescribed in the topic below; however, youmust first acquire a certificate from a trustedauthority, and then import the certificate files into Tableau Server. If you are running a TableauServer cluster and you want to use SSL, seeConfigure SSL for a Cluster on the next page,below, for recommendations.
Configure SSL
To configure Tableau Server to use SSL:
1. Acquire an Apache SSL certificate from a trusted authority (e.g., Verisign, Thawte,Comodo, GoDaddy, etc.). You can also use an internal certificate issued by yourcompany.Wildcard certificates, which allow you to use SSLwith many host nameswithin the same domain, are also supported.
Some browsers will require additional configuration to accept certificates from certainproviders. Refer to the documentation provided by your certificate authority.
2. Place the certificate files in a folder named SSL, parallel to the Tableau Server 8.2folder. For example:C:\Program Files\Tableau\Tableau Server\SSL
This location gives the account that's running Tableau Server the necessary permissionsfor the files.
3. Open the Tableau Server Configuration Utility by selectingStart > All Programs >Tableau Server 8.2 > Configure Tableau Server on the Start menu.
4. In the Configuration Tableau Server dialog box, select theSSL tab.5. SelectUse SSL for Server Communication and provide the location for each of the
following certificate files:
SSL Certificate File—Must be a valid PEM-encoded x509 certificate with theextension .crt
SSL Certificate Key File—Must be a valid RSA or DSA key that has an embeddedpassphrase, and is not password protected with the file extension .key
SSL Certificate Chain File (Optional)—Some certificate providers issue twocertificates for Apache. The second certificate is a chain file, which is a concatenation ofall the certificates that form the certificate chain for the server certificate. All certificates inthe file must be x509 PEM-encoded and the file must have a .crt extension (not .pem).
- 16 -
6. ClickOK. The changeswill take effect the next time the server is restarted.When the server is configured for SSL, it accepts requests to the non-SSL port (defaultis port 80) and automatically redirects to the SSL port 443. SSL errors are logged in theinstall directory at the following location. Use this log to troubleshoot validation andencryption issues.
C:\ProgramData\Tableau\TableauServer\data\tabsvc\logs\httpd\error.log
Tableau Server only supports port 443 as the secure port. It cannot run on acomputer where another application is using port 443.
Configure SSL for a Cluster
You can configure a Tableau Server cluster to use SSL. If the primary Tableau Server isthe only node that is running the gateway process (which it does by default), then that'sthe only place where you need to configure SSL. See the procedure above for steps.
- 17 -
SSL andMultiple Gateways
A highly available Tableau Server cluster can includemultiple gateways, fronted by aload balancer (learnmore). If you are configuring this type of cluster for SSL, you havetwo choices:
l Configure your load balancer for SSL.Traffic is encrypted from the client webbrowsers to the load balancer. Traffic from the load balancer to the TableauServer gateway processes is not encrypted. No SSL configuration in TableauServer is required, it's all handled by your load balancer.
l Configure Tableau Server for SSL: Traffic is encrypted from the client webbrowsers to the load balancer, and from the load balancer to the Tableau Servergateway processes. See the procedure below for details.
Configure a Server Cluster for SSL
When you configure a Tableau Server cluster to use SSL, you place the SSL certificateand key files on every computer that's running a gateway process. To configure aTableau Server cluster to use SSL:
1. Configure the load balancer for SSL passthrough. Refer to your load balancer'sdocumentation for assistance.
2. Make sure that the SSL certificate you use was issued for the load balancer's hostname.
3. Configure the primary Tableau Server as described in the procedure above.
4. Place the same SSL certificate and key file that you used for the primary on eachTableauWorker that is running a gateway process. Use the same folder locationon the workers that you used on the primary. You do not need to do any additionalconfiguration on the workers.
Take, as an example, a cluster that includes a primary Tableau Server and threeworkers. Gateway processes are running on the primary, Worker 2 andWorker 3.In this situation, you configure the primary Tableau Server for SSL, then copy thesame SSL certificate and key files toWorker 2 andWorker 3. Because these filesare in C:\ProgramFiles\Tableau\Tableau Server\SSL folder on the primary, theyare in that same location onWorker 2 andWorker 3.
SAMLYou can configure Tableau Server to use an external identity provider (IdP) to authenticateTableau Server users over SAML. All user authentication is done outside of Tableau,regardless of whether you're using Active Directory or local authentication in Tableau Server tomanage your user accounts on Tableau Server. This allows you to provide a single sign-onexperience across all the applications in your organization.
Before you configure Tableau Server for SAML, make sure youmeet theSAMLRequirements on page 291.
- 18 -
Configure SAML
To configure Tableau Server to use SAML:
1. Place the certificate files in a folder named SAML, parallel to the Tableau Server 8.2folder. For example:C:\Program Files\Tableau\Tableau Server\SAML
This location gives the account that's running Tableau Server the necessary permissionsfor the files.
2. SAML configuration is handled on theSAML tab, which displays during Tableau ServerSetup. If you are configuring SAML after Setup, access the SAML tab by opening theTableau Server Configuration Utility (Start > All Programs > Tableau Server 8.2 >Configure Tableau Server) and clicking theSAML tab.
3. On the SAML tab, selectUse SAML for single sign-on and provide the location foreach of the following:
Tableau Server return URL—TheURL that Tableau Server users will be accessing,such as http://tableau_server. Using http://localhost is not recommended, and an URLwith a trailing slash (for example, http://tableau_server/) is not supported.SAML entity ID—The entity ID uniquely identifies your Tableau Server installation tothe IdP. You can enter your Tableau Server URL again here, if you like, but it does nothave to be your Tableau Server URL.
SAML certificate file—APEM-encoded x509 certificate with the file extension .crt.This file is used by Tableau Server, not the IdP.
SAML certificate key file—AnRSA or DSA private key file that is not passwordprotected, and that has the file extension .key. This file is used by Tableau Server, notthe IdP.
4. Leave theSAML IdP metadata file text box empty for now and clickExport MetadataFile.
- 19 -
5. A dialog opens that allows you to save Tableau Server's SAML settings as an XML file.At this point, metadata from your IdP is not included.
Save the XML file with the name of your choice.
6. On your IdP's website or in its application:
l Add Tableau Server as a Service Provider.You will need to refer to your IdP'sdocumentation on how to do this. As part of this, you will import the file you savedin step 5.
l Confirm that your IdP usesusername as the attribute element to verify.7. Still within your IdP, export your IdP'smetadata XML file.
8. Copy your IdP'smetadata XML file to the following folder on your Tableau Servercomputer:
C:\Program Files\Tableau\Tableau Server\SAML
9. On the SAML tab in the Tableau Server Configuration dialog box, enter the location tothe file in theSAML IdP metadata file text box:
- 20 -
10. ClickOK. Tableau Server is now configured for SAML authentication.
Configure a Server Cluster for SAML
When you configure a Tableau Server cluster to use SAML, you place the same SAMLcertificate, SAML key, and SAML IdP metadata files on every computer that's running aTableau application server process (also known aswgserver). To configure a Tableau Servercluster to use SAML:
1. Configure the primary Tableau Server as described in the procedure above.
2. Place the same SAML certificate, SAML key, and SAML IdP metadata files that youused for the primary on each TableauWorker that is running an application serverprocess. Use the same folder location on the workers that you used on the primary. Youdo not need to do any additional configuration on the workers.
Take, as an example, a cluster that includes a primary Tableau Server and threeworkers. Application server processes are running on the primary, Worker 2 andWorker3. In this situation, you configure the primary Tableau Server for SAML, then copy thesame SAML certificate, SAML key, and SAML IdP metadata files toWorker 2 andWorker 3. Because these files are in the C:\ProgramFiles\Tableau\TableauServer\SAML folder on the primary, they are in that same location onWorker 2 andWorker 3.
Test Your Configuration
Test your SAML configuration by opening a fresh web browser instance and typing theTableau Server name in the URLwindow:
- 21 -
You should note that the sign in prompt that appears is from your IdP and not Tableau Server:
Add an Administrator AccountThe final step in activating Tableau Server is to add an administrator account. Theadministrator will have all access to the server including the ability to manage users, groups,and projects. Adding an administrator account differs depending on whether you are usingActive Directory or local authentication.
Active DirectoryIf you are using Active Directory, type theUsername andPassword for an existing ActiveDirectory user who will be the administrator. Then clickAdd user.
- 22 -
Note:If the administrator account is in the same domain as the server simply type the usernamewithout the domain. Otherwise you should include the fully qualified domain name. Forexample, test.lan\username.
Local AuthenticationIf you are using Local Authentication, create an administrative account by typing aUsername,Display Name, and aPassword (twice) of your choosing. Then clickAdd user.
Reconfigure the ServerEntering your Tableau Server configuration settings is part of Setup, but you can open theConfiguration dialog box after Setup tomake changes. See the steps below for details. You
- 23 -
can also use the tabadmin on page 338 command line tool to make configuration changes.Regardless of how youmake the change, the new settings are written to the configuration filetabsvc.yml, which is located in the config directory.
Note: You cannot switch between Active Directory and Local Authentication. These optionscan only be configured during Setup.
To change a setting in the Tableau Server Configuration dialog box, do the following:
1. Stop the server by selectingAll Programs > Tableau Server 8.2 > Stop TableauServer on theWindowsStart menu.
2. Next, selectConfigure Tableau Server on theWindowsStart menu.
3. If you are using an Active Directory account for the server’s Run AsUser account, enterits password on theGeneral tab.
4. Make your configuration change.
5. ClickOK.
6. Start the server by selectingAll Programs > Tableau Server 8.2 > Start TableauServer on theWindowsStart menu.
Reconfigure ProcessesTo change how processes are configured for a single server installation, follow the stepsbelow. If you are changing how processes are configured for a worker, refer to Install andConfigure Worker Servers on page 40.
1. You will need to stop Tableau Server to make this configuration change. From the Startmenu, clickAll Programs > Tableau Server 8.2 > Stop Tableau Server.
2. Open the Tableau Server Configuration dialog box from the Start menu by navigating toAll Programs > Tableau Server 8.2 > Configure Tableau Server.
3. Enter your Password, if necessary, on theGeneral tab then click theServers tab:
- 24 -
4. Highlight This Computer and clickEdit:
5. The Edit Tableau Server dialog box is where you change the number of processes:
6. You can run up to eight instances of the VizQL, application server, data server, orbackground processes—although this limit can be changed if necessary. SeeAboutthe Server Process Limit on page 35 for more information. Also, for Tableau Server tofunction, theremust always be one active instance of the data engine and the repository.For steps on how tomove them to another machine, seeMove the Data Engine andRepository Processes on page 34. For steps on how to configure standby instances ofthem, refer toHigh Availability on page 45.After youmake your changes, clickOK, then clickOK again to exit the Configurationdialog box.
7. Start Tableau Server again. From the Start menu, clickAll Programs > Tableau
- 25 -
Server 8.2 > Start Tableau Server.
Tableau Server Processes
There are six Tableau Server processeswhose default configuration you can change toachieve different results. The topics Improve Server Performance on page 228 andHighAvailability on page 45 describe some of the approaches you can take. High-level status foreach process is displayed on the server’sMaintenance page andmore detailed informationrelated to some of the processes—such as the background process—is in theAdministrativeViews on page 155 topic.Architecturally, the 64-bit version of Tableau Server uses native, 64-bit processes; the 32-bitversion of Tableau Server uses 32-bit processes. The exception is the data engine. If the 32-bitversion of Tableau Server is installed on a 64-bit operating system, the 64-bit version of thedata engine process is used.
For information on log files generated by these processes, seeServer Log File Locations onpage 379.
Process File Name Purpose Multi-Threaded?
PerformanceCharacteristics
applicationserver
wgserver.exe Handles the webapplication,supports browsingand searching
Yes Only consumesnoticeable resourcesduring infrequentoperations, likepublishing a workbookwith an extract, orgenerating a static imagefor a view. Its load can becreated by browser-based interaction and bytabcmd.
background backgrounder.exeExecutes servertasks, includingextract refreshes,‘Run Now’ tasks,and tasks initiatedfrom tabcmd
No A single-threadedprocesswheremultipleprocesses can be run onany or all machines in thecluster to expandcapacity. Thebackgrounder normallydoesn’t consumemuchprocessmemory, but itcan consumeCPU, I/O,or network resourcesbased on the nature ofthe workload presentedto it. For example,performing large extract
- 26 -
Process File Name Purpose Multi-Threaded?
PerformanceCharacteristicsrefreshes can usenetwork bandwidth toretrieve data. CPUresources can beconsumed by dataretrieval or complextabcmd tasks.
data engine tdeserver64.exe
tdeserver.exe
Stores dataextracts andanswers queries
Yes The data engine'sworkload is generated byrequests from the VizQLServer process. It is thecomponent that loadsextracts intomemoryand performs queriesagainst them. Memoryconsumption is primarilybased on the size of thedata extracts beingloaded. The 64-bit binaryis used as the default on64-bit operatingsystems, even if 32-bitTableau Server isinstalled. The dataengine ismulti-threadedto handlemultiplerequests at a time.Under high load it canconsumeCPU, I/O, andnetwork resources, all ofwhich can be aperformance bottleneckunder load. At high load,a single instance of thedata engine canconsume all CPUresources to processrequests.
data server dataserver.exe Handlesconnections toTableau Serverdata sources
Yes Because it’s a proxy, it’snormally only bound bynetwork, but it can bebound byCPU with
- 27 -
Process File Name Purpose Multi-Threaded?
PerformanceCharacteristicsenough simultaneoususer sessions. Its load isgenerated by browser-and Tableau Desktop-based interaction andextract refresh jobs forTableau Server datasources.
repository postgres.exe Tableau Serverdatabase, storesworkbook anduser metadata
n/a Normally consumes fewresources. It canbecome a bottleneck inrare cases for very largedeployments (thousandsof users) whileperforming operationssuch as viewing allworkbooks by user orchanging permissions.
VizQLServer
vizqlserver.exe Loads andrenders views,computes andexecutes queries
Yes Consumes noticeableresources during viewloading and interactiveuse from aweb browser.Can be CPU bound, I/Obound, or networkbound. Process load canonly be created bybrowser-basedinteraction. Can run outof processmemory.
About the Server Process Limit
Thewgserver, data engine, data server, and VizQL server processes are engineered to bemulti-threaded andmulti-processed. A single process instance can run over 16 threads. Bydefault, Tableau Server installs with up to two instances of each server process.
If you are running the 64-bit version of Tableau Server (which is available starting withversion 8.1), two instances of a process is themost you should run.
If you are running the 32-bit version of Tableau Server and the default settings aren’tsufficient, you can change them to up to eight instances either during Setup (for upgrades only)or after Setup, using the Configuration dialog box. Eight instances of a process is the defaultupper limit. If your machine has enough RAMandCPU cores, you can change the upper limit
- 28 -
using the service.max_procs tabadmin setting. For each process instance, Tableaurecommends that themachine running the process have at least 1 GB of RAMand 1 logicalCPU core.
To change themaximumnumber of processes allowed:
1. After Setup, stop the server.
2. Still in the Tableau Server bin directory, enter the following command, where number isthemaximumnumber of process instances you want to allow:tabadmin set service.max_procs number
For example:tabadmin set service.max_procs 10
3. Start the server so the changes can take effect.
- 29 -
Upgrade to 8.2Use the following topics to upgrade your Tableau Server software to version 8.2. If you areupgrading from a version earlier than 8.1, please refer to the Tableau Knowledge Base.
Pre-Upgrade ChecklistHere are items you should locate and steps you should perform before you upgrade TableauServer to version 8.2.x.
Note: A new version of tabcmd is released with every release of Tableau Server. If youinstalled the command line utility on computers that are not running Tableau Server, youmay need to upgrade tabcmd on those computers when you upgrade Tableau Server.For more information see Install tabcmd on page 319.
Credentials, Setup Files, and CustomizationsBefore you upgrade, make sure you have the following:
l User account credentials: For each computer you’re upgrading, you need credentialsfor a user account with local admin permissions.
l Run As account credentials: Confirm that you have the user name and password forTableau Server’s Run As account. If you are using NT AUTHORITY\NetworkService(the default), no password is required.
l Setup files: In addition to having the .exe for the upgrade you’re about to perform, youshould locate or re-download the Setup .exe for the server version you currently have inproduction (see Downloading Tableau Products). If something unexpected happensduring the upgrade, this can help you recover more quickly.
While Tableau retains configuration settings during an upgrade, it’s a best practice to also noteany customizations you’vemade so that you can verify them later. These include configuringSSL, changing Tableau’s default port and time out values, as well as using custom logos. Also,if you added your current Tableau Server version to your WindowsPATH environmentvariable, you will need to update that entry after upgrading so that it refers to the newer versionof Tableau Server.
Bit VersionStarting with version 8.1, Tableau Server is provided as a native 64-bit application aswell as a32-bit application. Earlier versions of Tableau Server were only available as 32-bit.
If you were previously running the 32-bit version of Tableau Server on a 64-bit operatingsystem, upgrading to the 64-bit version of Tableau Server is recommended. SeeBefore youinstall... on page 3 for theminimum requirements.
- 30 -
If you are upgrading a distributed installation of Tableau Server, the entire cluster must run thesame bit version—either all 32-bit or all 64-bit Tableau server software.When upgrading fromthe 32-bit version of Tableau Server to the 64-bit version, youmust first uninstall the 32-bitversion on each worker before installing the 64-bit version of the worker software. For moreinformation, seeUpgrading a distributed installation of Tableau Server from 32-bit to64-bit on page 34.
Check Your Product Maintenance StatusIf you attempt to upgrade Tableau Server from a server whosemaintenance has expired, theresult will be an unlicensed instance of Tableau Server.
To see whether your server’s maintenance has expired:
l SelectStart > All Programs > Tableau Server >Manage Product Keys and lookunder theMaintenance Expires column.
If your maintenance has expired, select the key and clickRefresh. If themaintenance datedoesn't update, contact Tableau Customer Support. Reactivating the product keywill be partof Setup. SeeActivate Tableau on page 5 for details. If your server doesn’t have internetaccess, refer toActivate Tableau Offline on page 6.
Create a “Clean” BackupIn addition to your regular Tableau Server backups, it’s a best practice to create a backup justprior to upgrading. Before you create the backup, run the tabadmin cleanup command toremove non-essential files from your backup. See Running Cleanup andBack Up theTableau Data on page 366 for steps.
Distributed Installations Only: Whether to Remove Workers Before Creating theBackupThe Tableau backup file (.tsbak) includes configuration information aswell as data. Therefore,a backup of a distributed installation of Tableau Server will include configuration informationabout the workers, including their IP addresses. If you don’t want this information as part ofyour backup (for example, because you aremigrating workers to new hardware as part of yourupgrade), you can do one of two things:
- 31 -
l Remove the workers from the Tableau Server configuration before creating the backup.
l Plan on using the --no-config option when you restore the backup file to your newinstallation. Note that with this option, no configuration information is restored—includingthe primary Tableau Server’s.
If you are running a distributed installation of Tableau Server and have a worker runningWindowsXP or WindowsServer 2003 SP1 or higher, youmust remove it from theconfiguration before upgrading. These operating systems are not supported platforms inversion 8.2. Note thatWindowsServer 2003 R2 SP2 or higher is supported.
To delete a worker from your Tableau Server configuration:
1. Stop the server on the primary Tableau Server.
2. On the primary server, open the configuration utility by selecting Tableau Server<version> > Configure Tableau Server on the Start menu.
3. In the Configuration dialog box, select theServers tab.4. If the worker is hosting extracts and/or the repository, move those services onto another
machine. SeeMove the Data Engine and Repository Processes on page 34 forsteps.
5. Next, highlight the worker and clickDelete.6. ClickOK.
7. Start the server.
Running CleanupRunning the tabadmin cleanup command removes files from the Tableau Server system thatyou don’t need in your backup file. You should run cleanup once with the server running, whichallows it to act on the Tableau database, and once with the server stopped, which allows it toremove log files.
To run tabadmin cleanup:
- 32 -
1. Open a command prompt as an administrator:
2. Navigate to your Tableau Server bin directory. For example:cd “C:\Program Files (x86)\Tableau\Tableau Server\8.1\bin”
3. Confirm that the server is running:tabadmin status
4. Run cleanup by typing the following:tabadmin cleanup
5. Stop the server:tabadmin stop
6. Run cleanup again:tabadmin cleanup
Keep the server stopped for creating a backup (next).
Create the Backup FileThe tabadmin backup command creates a .tsbak file containing data from your repository, dataextracts, and server configuration. After you create the file, store it on a separate computer.SeeBack Up the Tableau Data on page 366 for steps. Note that if you are creating a backupusing Tableau Server version 8.0 or earlier, youmust stop the server before creating a backup.Starting with version 8.1, you can create a backup without stopping the server first.
Distributed installations only: If you removed workers from your server configurationprior to creating your backup and you are not migrating to new hardware as part of yourupgrade, you can now add the workers back to your configuration. Follow the steps in
- 33 -
Upgrade to 8.2 below. Otherwise, if you aremigrating to new hardware as part of yourupgrade, leave the workers off the configuration. SeeMigrate to New Hardware onpage 36 for details.
Upgrade to 8.2After you’ve completed thePre-Upgrade Checklist on page 29, upgrade your existingTableau Server installation to version 8.2 by following one of the procedures below. If you aremigrating to new hardware as part of your upgrade, refer toMigrate to New Hardware onpage 36 instead of the procedures below.
When you install the newer version of Tableau Server, use the same drive and directory thatthe earlier version used. This way, data and configuration settings from your earlier version canbe automatically imported.
If you are upgrading from 32-bit Tableau Server to 64-bit Tableau Server youmust uninstallyour existing version before installing the new version.
Single Server InstallationsTo upgrade a single server installation of Tableau Server to version 8.2 or 8.2.x:
1. Use Add/Remove Programs on your Tableau Server to uninstall the earlier version.
Uninstalling removes the server software but leaves your data and configuration settingsintact.
2. Install Tableau Server. Tableau Server Setup will handle importing the data andconfiguration settings from your earlier version.
Distributed InstallationsIf you aremoving your cluster to the 64-bit version of Tableau Server as part of your upgrade toversion 8.2, review the guidelines on "bit version" in thePre-Upgrade Checklist on page 29.
To upgrade a distributed installation of Tableau Server from version 8.1 to version 8.2or 8.2.x:
1. Use Add/Remove Programs on the primary Tableau Server to uninstall the earlierversion.
2. Use Add/Remove Programs on the worker servers to uninstall the earlier version.
Uninstalling removes the server software but leaves your data and configuration settingsintact.
3. Install TableauWorker Server on the worker servers.
4. Install Tableau Server on the primary Tableau Server.
- 34 -
Tableau Server Setup handles importing the data and configuration settings from yourearlier version.
To upgrade a distributed installation of Tableau Server from version 8.2.x to version8.2.x:
1. Use Add/Remove Programs on your primary Tableau Server to uninstall the earlierversion.
Uninstalling removes the server software but leaves your data and configuration settingsintact.
2. Install Tableau Server on your primary Tableau Server. In most cases, with a "sameversion" upgrade (version 8.2.x to 8.2.x), the primary Tableau Server pushes updates tothe worker servers. so there is no need to uninstall and reinstall server software on theTableau workers.
Note: If there is an update to PostgreSQL drivers or other third-party software,Tableau workers cannot be upgraded automatically. During upgrading amessagetells you that "One or more workers could not be upgraded automatically" andinstructs you tomanually upgrade the software on each worker. This can happeneven during a "same version" upgrade.
If you are upgrading from 32-bit Tableau Server to 64-bit, you need to uninstall andreinstall. See Upgrading distributed installation of Tableau Server from 32-bit to 64-bitbelow.
Tableau Server Setup will handle importing the data and configuration settings fromyour earlier version.
Upgrading a distributed installation of Tableau Server from 32-bit to 64-bit
If you are upgrading a distributed installation from 32-bit to 64-bit, you need to take thefollowing steps:
1. Use Add/Remove Programs on your primary Tableau Server to uninstall the 32-bitversion from the primary server.
2. Use Add/Remove Programs on your Tableau Server workers to uninstall the 32-bitversions.
3. Install 64-bit Tableau Server on each worker.
4. Install 64-bit Tableau Server on your primary Tableau Server.
Move the Data Engine and Repository ProcessesIf you need to delete a worker from the Tableau Server configuration and that worker is hostingthe only instance of the repository or the data engine (which hosts extracts), youmust first
- 35 -
move the process onto another machine. This is because theremust always be one activeinstance of the repository and data engine processes.
Tomove the data engine or repository processes:
1. If you haven’t done so already, stop the primary Tableau server and open the TableauServer Configuration dialog box (Start > Tableau Server 8.2 > Configure TableauServer) on the primary Tableau Server.
2. On theServers tab, highlight the IP address or computer name of the computer ontowhich you want to move the process. It can be another worker or the primary (ThisComputer (Primary)).
3. ClickEdit.4. In the Edit Tableau Server dialog box, select the check box for the process you are
moving: eitherData Engine,Repository or both, and clickOK.5. ClickOK in the Tableau Server Configuration dialog box.
6. Start the primary Tableau server so that the changes can take effect.
7. Stop the server and open the Tableau Server Configuration dialog box.
8. On theServers tab, highlight the IP address or computer name of the worker fromwhich you are removing the process and clickEdit.
9. Clear the check box for the process youmoved and clickOK.
10. ClickOK again and start the primary server so that the changes can take effect.
If you are performing this procedure as part of deleting a worker from the Tableau Serverconfiguration (as described in thePre-Upgrade Checklist on page 29) stop the server againbefore proceeding.
About the Server Process LimitThewgserver, data engine, data server, and VizQL server processes are engineered to bemulti-threaded andmulti-processed. A single process instance can run over 16 threads. Bydefault, Tableau Server installs with up to two instances of each server process.
If you are running the 64-bit version of Tableau Server (which is available starting withversion 8.1), two instances of a process is themost you should run.
If you are running the 32-bit version of Tableau Server and the default settings aren’tsufficient, you can change them to up to eight instances either during Setup (for upgrades only)or after Setup, using the Configuration dialog box. Eight instances of a process is the defaultupper limit. If your machine has enough RAMandCPU cores, you can change the upper limitusing the service.max_procs tabadmin setting. For each process instance, Tableaurecommends that themachine running the process have at least 1 GB of RAMand 1 logicalCPU core.
To change themaximumnumber of processes allowed:
- 36 -
1. After Setup, stop the server.
2. Still in the Tableau Server bin directory, enter the following command, where number isthemaximumnumber of process instances you want to allow:tabadmin set service.max_procs number
For example:tabadmin set service.max_procs 10
3. Start the server so the changes can take effect.
Migrate to New HardwareUse the following procedure tomigrate Tableau Server from one computer to another.Specifically, these steps describe how tomove Tableau Server data and configuration settingsfrom your in-production computer to a new computer where Tableau Server version 8.2 isinstalled. Before you start, make sure you have followed the steps in thePre-UpgradeChecklist on page 29, including creating a .tsbak file.
1. Install Tableau Server on the new computer.
2. Copy your .tsbak file to the bin folder on your new Tableau Server (for example,C:\ProgramFiles\Tableau\Tableau Server\8.2\bin).
3. Next, stop Tableau Server.
4. Restore your in-production data without configuration information to your new TableauServer installation:tabadmin restore --no-config <filename>
where <filename> is the name of the .tsbak file. For example:tabadmin restore --no-config mybackup.tsbak
The --no-config option restores the data from your in-production Tableau Serverbut excludes configuration information. You need to use this option whenmoving to newhardware because otherwise you will have conflicts with the old configuration. Afterdoing the restore, youmay need to reconfigure some options (SMTP or proxy settings,for example).
5. Start the server.
6. Distributed installations only: Run the Tableau worker installer on all the additionalcomputers you want to add to your Tableau Server cluster. See Install and ConfigureWorker Servers on page 40 for steps.
7. The same Tableau Server product key can be activated three times: once for aproduction environment, once for a test environment, and once for a QA environment.After you have tested your new Tableau Server installation and confirmed that it's readyfor production, youmust deactivate your earlier production version of Tableau Server,and then youmust uninstall it. To deactivate the earlier version:
- 37 -
- SelectStart > All Programs > Tableau Server > Manage Product Keys.- For each product key, select the product key and clickDeactivate.
If you do not have an internet connection, you are prompted to create an offlineactivation file to complete the deactivation process. SeeActivate TableauOffline on page 6 for steps.
- 38 -
Distributed EnvironmentsUse the topics below to learnmore about running a distributed installation of Tableau Server:
Distributed RequirementsBefore you start to configure a Tableau Server cluster, make sure youmeet the followingrequirements.
HardwareWhile the computers you use in your cluster must meet the requirements described inBeforeyou install... on page 3, they do not need to be identical.
Hardware Guidelines for High Availability
Here are some guidelines for the systems you use for failover and high availability:
l Failover—two or three computers: To configure a cluster that provides failoversupport for the data engine and repository processes, you need at least two computersor VMs: one for the primary Tableau Server and one for a Tableau worker. In thisconfiguration, a website or computer that isn't running Tableaumay also be needed(learnmore). The recommended failover configuration requires three computers orVMs: one for the primary Tableau Server and two for the workers.
l Failover & multiple gateway support—two or three computers and a loadbalancer: To configure a cluster that provides the above plus support for multiplegateways, you need at least two computers or VMs, and a load balancer to front thecluster. The recommended failover configuration with support for multiple gateways isthree computers or VMs and a load balancer.
l High availability—four computers and a load balancer: To configure for highavailability, you need the resources described above plus an additional computer to bethe backup primary for your primary Tableau Server.
l Primary computers: If you configure for high availability, the primary Tableau Serverand the backup primarymay be running few or no Tableau Server processes.Therefore, the computers that run the primary and backup primary do not need asmanycores as the ones running your worker servers. You will, however, need adequate diskspace for backups because the primary computer is used during the database backupand restore processes. In addition to the amount of space needed for the backup file,you need temporary disk space roughly 10 times the size of the backup file (so if yourbackup is 4 GB, you should have about 40GB of temporary disk space available).
SoftwareTableau Server is available in 32- and 64-bit versions. If you are running a Tableau Servercluster, each computer must run the same bit version—either all 64-bit or all 32-bit. Forexample, if the primary Tableau Server is running the 64-bit version of Tableau Server, the
- 39 -
workers in the cluster must run the 64-bit version of Tableau Server Worker. They can't run the32-bit version of Tableau Server Worker.
Networking and Ports
l Ports: As with any distributed system, the computers or VMs you use need to be able tocommunicate with one another. See TCP/IP Ports on page 313 for a list of ports thatmust be available on the gateways and workers.
l Same domain: All computers in a cluster must bemembers of the same domain. Theserver'sRun As User on page 298 account, which is specified on the primary TableauServer, must be a domain account in this same domain.
l Static IP addresses: Any computer running Tableau Server, whether it's a singleserver installation or part of a cluster, must have a static IP address (learnmore).
Best PracticesHere are some things to keep inmind before you start to install and configure:
l IP addresses or computer names: Note the IPv4 addresses or computer names ofeach computer or VM you’ll be working with. You will need to provide them duringTableauWorker Setup and configuration. Asmentioned above, each computer in thecluster must use a static IP address, even if you use the computer's name to identify itduring configuration.
l CNAME record: If you’re configuring for high availability and you are not using a loadbalancer, make sure your primary Tableau Server and backup primary have the sameCNAME record so that your Tableau Server users have a smooth experience if oneprimary fails and you configure the other to take over. If you are using a load balancer,it's the load balancer's name that users will be using as the Tableau Server URL,regardless of the gateway that's actually handling the request.
l User account credentials: For each computer, you need credentials for a useraccount with local admin permissions. If you’re configuring for high availability, the RunAs account you use for your primary Tableau Server must be the same as the one youuse for your backup primary Tableau Server.
l Backup: It’s a best practice to create a backup prior to making significant systemchanges. SeeBack Up the Tableau Data on page 366 for steps.
SSLIf you are planning to configure SSL for a highly available Tableau Server cluster with multiplegateways and a load balancer (learnmore), make sure that the SSL certificate you use wasissued for the load balancer's host name. SeeConfigure SSL for a Cluster on page 16 forother details.
- 40 -
Hostname Support in Tableau ServerStarting with version 8.1, hostname support was added to Tableau Server. Thismeans thatwhen you're configuring Tableau Server to work with another computer, you can use the nameof that computer to identify it, instead of its static IPv4 address. Internally, however, TableauServer still relies on IP addresses to communicate with various services, such as Tableauworkers or trusted hosts. So even if you provided the name of a computer instead of its IPaddress, the IP address associated with that computer can't change or be temporary.
If a computer running Tableau Server gets a new IP address—for example, after a VM reboot,or in a network environment that's using DHCP—you need to run tabadmin config toupdate Tableau Server's configuration with the change. See the procedure below for steps.
In addition to DHCP, another item that could result in an IP address changing, post-Setup, is aWindows operating system feature for IPv6 addresses called "temporary IPv6 addresses".See the Knowledge Base for details on how to identify and disable this feature.To update the Tableau Server configuration:
1. On the primary Tableau Server, open a command prompt as an administrator.
2. Type the following:
cd "C:\Program Files\Tableau\Tableau Server\8.2\bin"
3. Stop the server:
tabadmin stop
4. Update the server's configuration by typing the following:
tabadmin config
5. Start the server:
tabadmin start
Install and Configure Worker ServersAfter you complete the initial configuration, you can set up Tableau Server to run onmultiplecomputers. This is called a distributed installation, or cluster. Running a distributed installationuses additional ports on the primary Tableau Server and requires that certain ports beavailable for binding during Setup on the TableauWorker Servers. See TCP/IP Ports on page313 for more information. There are also additional requirements to be aware of when you runa distributed installation. SeeDistributed Requirements on page 38 for details.
To install and configure a TableauWorker Server:
1. Make sure you’ve installed Tableau Server on the primary computer.
2. Stop the server on the primary (see Tableau Server Monitor on page 139 to learnhow).
- 41 -
3. Download the Tableau Server Worker software from the Tableau Customer AccountCenter.
4. Run Tableau Server Worker Setup on all additional computers that you want to add tothe Tableau Server cluster.
5. During installation you will be asked to provide the IPv4 addresses or computer name ofthe primary server. Using a computer name is recommended.
If the primary hasmultiple network interface cards (NICs) enabled and you choose toenter IPv4 addresses, enter all of the primary's IPv4 addresses, separating each with acomma. The IP address(es) for the computer running the primarymust be static, thisapplies even if you use a computer name to identify the primary (learnmore).
If you have a worker runningWindows 7 withWindows Firewall enabled, refer to theTableau Knowledge Base before proceeding.
6. Once theWorker software is installed on worker computers, and with the primaryTableau Server still stopped, return to the primary server and open the configurationutility by selecting Tableau Server 8.2 > Configure Tableau Server on the Startmenu.
7. In the Configuration Utility, enter your password on theGeneral tab then select theServers tab and clickAdd.
Note: Click theDiscover button to automatically add anyworker computersconfigured in step 5 (above) with the IPv4 address or name of the computer onwhich you are running the configuration utility.
8. In the next dialog box, type the IPv4 address or computer name for one of the workercomputers and specify the number of VizQL,Application Server,Data Server,Background, andData Engine processes to allocate to the computer.With the 64-bit version of TableauWorker Server, you can run up to two instances ofeach process. In rare cases and if the server's hardware allows, that limit can bechanged. SeeAbout the Server Process Limit on page 35 andPerformance onpage 226 for more information.
- 42 -
By default, the data engine, repository, and gateway are hosted on the primary server.Running these processes on an additional server, or moving them off of the primaryserver, is part of configuring for high availability. SeeHigh Availability on page 45 formore information.
9. ClickOK. It may take several minutes for the updates to complete.10. Repeat these steps for each computer you want to add to the distributed environment.
When you're finished adding workers, clickOK again to save the changes, then start theprimary Tableau Server.
Database DriversThe installers for Tableau Server and Tableau Server Workers automatically install drivers forOracle andOracle Essbase databases. If you plan to publish workbooks and data sources thatconnect to other databases, you will need tomake sure that both your primary and workerservers have the corresponding drivers.
Workers running VizQL, application server, data server, or backgrounder processes needthese database drivers. For example, if you have a worker dedicated as a VizQL server andanother computer dedicated to extract storage, you only need to install drivers on the computerrunning the VizQL server process.
Server processRequires data-base driver?
VizQL yesApplication server yesData server yes
- 43 -
Server processRequires data-base driver?
Background yesData engine (extract storage) noRepository noGateway no
Reinstall and Configure Worker ServerYoumight need to reinstall one of your Tableau worker servers. To do so, follow one of theseprocedures. The specific steps you take depend on whether or not the worker you arereinstalling has data engine or repository components on it and whether or not these areduplicated on any other node in the installation.
Note: Reinstallingmultiple workers at the same time could lead to data loss.
Use the following procedure to help you reinstall and configure a worker node that is hostingthe only data engine or repository in the distributed installation.
To reinstall the worker hosting the data engine or repository instance
1. Create a full backup of Tableau Server. For more information, seeBack Up theTableau Data on page 366.
2. Stop Tableau Server on the primary by selecting Tableau Server 8.2> Stop TableauServer on theWindowsStart menu, or by running the tabadmin stop commandfrom the command line.
3. On the Start menu, select Tableau Server 8.2 > Configure Tableau Server.4. In the Configuration Utility:
l On theGeneral tab, enter your password.l On theServers tab, add the data engine and/or repository components that theworker is hosting to another worker or to the primary, and then save yourchanges.For example, if the worker you are reinstalling currently hosts the data engine,add the data engine to another node.
5. Start Tableau Server and let it run for a few minutes to complete synchronizationbetween the worker you are reinstalling and the worker or primary on which you addedthe data engine and/or repository components.
6. Confirm that synchronization is complete by comparing the follow folders on the workeryou are reinstalling and the primary or worker to which you added the data engine andrepository. The size and contents of these folders should be identical:
- 44 -
l Data engine folder: ProgramData\Tableau\TableauServer\data\tabsvc\dataengine
l Repository folder: ProgramData\Tableau\TableauServer\data\tabsvc\pgsql
Note: If you do not confirm that synchronization is complete by comparingthe folders, youmay lose data when you continue.
7. Stop Tableau Server.
8. In the Configuration Utility:l On theGeneral tab, enter your password.l On theServers tab, select the worker you want to reinstall and then clickDelete.l Save your changes.
9. Start Tableau Server and verify that everything is working as expected.
10. On the worker:l Uninstall the Tableau Server worker software fromWindowsControl Panel.l Delete (or rename) the following folders: C:\Program Files\Tableau andC:\ProgramData\Tableau (\ProgramData is a hidden folder).
l Install the updated worker software.
11. On the Tableau Server primary, stop Tableau Server, add the worker back into theconfiguration, and then save the changes.
Note: The data engine and repository need to remain on at least one node whileyou are re-adding the worker.
12. Start Tableau Server.
Use the following procedure to help you reinstall and configure a Tableau worker that is eithernot hosting a data engine or repository, or is hosting a component but there is an additionalnode that is hosting the same component..
To reinstall and configure the worker node that is either not hosting a component orhosting a component that is being hosted on another node
1. Create a full backup of Tableau Server.
2. Stop Tableau Server on the primary by by selecting Tableau Server 8.2 > StopTableau Server on the Start menu or by running the tabadmin stop command at acommand prompt.
3. Open the configuration utility by selecting Tableau Server 8.2 > Configure TableauServer on the Start menu.
- 45 -
4. In the Configuration Utility:l On theGeneral tab, enter your password.l On theServers tab, select the worker you want to reinstall and then clickDelete.l Save your changes.
5. Start Tableau Server and verify that everything is working as expected.
6. On the worker:l Uninstall the Tableau Server Worker software fromControl Panel.l Delete (or rename) the following folders: C:\Program Files\Tableau andC:\ProgramData\Tableau. (\ProgramData is a hidden folder somay not bevisible.
l Install the updated worker software.
7. On the primary node, stop Tableau Server, use the configuration utility to add the workerback into the configuration, and then save the configuration.
Note: The data engine and repository need to remain on at least one node whileyou are re-adding the worker.
8. Start Tableau Server.
Maintain a Distributed EnvironmentAfter you set up a primary and one or more worker servers for a distributed installation, you canperform all subsequent configuration and updates from the primary server, using the commandline tools and configuration utility on the primary server. Updateswill be pushed to the workersautomatically.
When you installed worker servers, you specified the primary's IPv4 address or computername. If that IP address or computer name changes, you will need to re-install the workerservers.
You canmonitor the status of the Tableau Server cluster on the server Maintenance page. SeeServer Maintenance on page 131 to learnmore about maintaining the server.
High AvailabilityUse the links below to learnmore about Tableau Server’s support for high availability:
Understanding High AvailabilityIf you’re configuring a Tableau Server system for high availability, the steps you perform are allabout building in redundancy, thus reducing your potential downtime. The four areas that
- 46 -
require redundancy are the data engine, repository, and gateway processes, and the primaryTableau Server, which runs the server's licensing component. Because theremust always beone active instance of the data engine and repository processes, configuring the cluster is amulti-phased procedure that requires the primary Tableau Server to be stopped and restartedat certain points so that settings can take effect. For exact steps, seeConfigure for Failoverand Multiple Gateways on page 50 andConfigure a Backup Primary on page 60. Seedistrib_requ.htm aswell.
The topics below summarize how your server system topology evolves as you configure it forhigh availability. Theminimum recommended configuration for high availability is a three-nodesystem. This includes a primary server to run licensing and two workers to host themainprocesses. You can increase reliability of the system by adding a fourth computer to serve as abackup primary. If you run a gateway process on all nodes, it alsomakes sense to use a loadbalancer for the gateways.
A Single Server System
After you install the primary Tableau Server, it is running at least one instance of all serverprocesses. This is themost basic configuration of Tableau Server. It has no redundancy.
Here’s what the Status table on theMaintenance page typically looks like for a single-serversystem:
To build in redundancy, you need to add additional servers to host the active and standby dataengine and repository processes. In addition, to reduce the system’s vulnerability, multiple
- 47 -
gateways can be run, and the primary should be isolated on its own node, ideally running asfew of the server processes as possible. The fewest number of computers required to achievethis is three (seeA Three-Node System on the next page); however, you can achieve someredundancywith two computers.
A Two-Node System
If you have hardware constraints and a three-node cluster is out of reach, you can gain someredundancy using two computers and a host that's external to your Tableau Server cluster.
In the above system, the primary Tableau Server and a worker server are running the activeand standby instances of the data engine and the repository, as well as gateways. A thirdcomputer, external to the Tableau Server cluster is being used as a third point of contact for thetwo gateways. Here's why:When a Tableau server that's running the data engine or therepository loses connectivity with the other nodes, it checkswith a gateway process external toitself (but still within the Tableau Server cluster) to determine which node failed and whetherany standby processes now need to become active. In a two-node cluster, if connectivity is lost,it's not possible to reach that other Tableau gateway process. In these cases, a website orcomputer outside the Tableau Server cluster can be used. SeeConfirm Failover Externallyon page 56 for how to configure this.
Here's what the Status table for the above configuration looks like. Because the third computerisn't a Tableau server, it's not listed in the table.
- 48 -
A Three-Node System
While the two-node system described above provides some failover support for the dataengine and repository processes, a three-node systemwould help you reduce the primary'svulnerability:
The Status table on theMaintenance page looks similar to the following:
In a three-node cluster, the data engine and repository processes have beenmoved from theprimary to a worker, and the primary is only running the gateway process. Because search andlicensing functionality are integral to the primary and can't be removed, they are not displayed
- 49 -
in the Status table. In this configuration, if your active worker fails, the standbyworkerautomatically becomes active. Exactly how to create this three-node cluster, including how toadd the workers and remove the processes from the primary, is described inConfigure forFailover and Multiple Gateways on the next page.There are still two things you can do to improve this three-node cluster: 1) add a load balancerto interface with the three active gateways, and 2) create a backup to address the single pointof failure: the primary. See the topics below for details.
Add a Load Balancer
At this point, all three nodes have gateways, which are used to route requests to availableserver processes. Unlike the repository process, there aren't active and standby gateways. Allgateways are active. To further reduce your cluster's potential for downtime, you shouldconfigure a load balancer.
Add a Backup Primary
Adding a backup primary provides a safeguard for your system. The backup primary is anadditional server added to the system to be ready if your primary fails. While it is not an activeserver, after you complete the first set of steps inConfigure a Backup Primary on page 60, itis ready to be activated.While the backup primary needs to be licensed during installation, itdoes not count as one of the three environments allowable under the Tableau EULA.
Here’s what the system looks like with a backup primary:
- 50 -
The Status table for the above configuration looks the same as for a three-node system. If theprimary fails and you perform the steps for the backup primary to take over, your system is backonline using the new primary:
The primary Tableau Server is the only place where licensing can be run. Licensing is checkedevery 8 hours. If the primary is only running the licensing component, and depending on whenthe licensing check last occurred, you have up to 8 hours to bring the backup primary online.During that window of time, the cluster will continue to function. For example, if the licensingcheck occurred 7 hours and 50minutes ago, you have 10minutes. If the licensing checkoccurred 1minute ago, you have 7 hours and 59minutes.
Configure for Failover and Multiple GatewaysDo the following to configure a three-computer cluster that providesmultiple gateways andfailover support.
- 51 -
1. Install Tableau Server on your primary computer.
2. After Setup completes, check the Status table on theMaintenance page. All theprocesses should have a green “waiting for request” status:
3. Stop the server on the primary.
4. Run TableauWorker Setup on the two additional computers or VMs that will providefailover and extra gateway support. DuringWorker Setup, you will need to provide thecomputer name (recommended) or IPv4 addresses of the primary Tableau Server. Ifyou enter multiple IPv4 addresses, separate each with a comma.
A static IP addressmust be assigned to the primary, even if you are using theprimary's computer name to identify it (learnmore).
5. With the primary server still stopped, open its Configuration dialog box: Start > AllPrograms > Tableau Server > Configure Tableau Server. On theGeneral tab enterthe Run As account password.
6. On the Servers tab, clickAdd to add a worker.7. Enter the IPv4 address or computer name of the worker, enter 1 forData Engine and
select theRepository check box. For now, leave theGateway check box cleared. Youwill add a gateway to this worker later.
- 52 -
If you want the worker to run other server processes, enter the number of instances youwant to run, such as 1 or 2. ClickOK to close the Add Tableau Server dialog box.
8. Start the server on the primary.
9. Important: Allow several minutes for the server's synchronization processes to copydata. This can take anywhere from 5minutes to 15minutes (or evenmuch longer)depending on the size of your installation and the number of extracts.
10. Confirm that the synchronization is complete by comparing the following folders on theprimary and first worker server:
l Data engine folder:ProgramData\Tableau\TableauServer\data\tabsvc\dataengine
The contents and size of this folder on the primary and first worker should beidentical.
l Repository folder: ProgramData\Tableau\TableauServer\data\tabsvc\pgsql
The size of this folder on the primary and first worker should be identical, or closeto identical.
Not confirming the above before you stop the server in the next step can result inloss of data.
11. After you've confirmed that the synchronization is complete, stop the server on theprimary.
12. Open the Configuration dialog box and clickAdd on the Servers tab to add anotherworker.
- 53 -
13. Enter the IPv4 address or computer name of the second worker, enter at least 1 forevery process but theData Engine (set that to 0). Clear theRepository check box andselectGateway.
You do not need to specify which worker is active and which is standby for the dataengine and repository.
ClickOK.
14. On the Servers tab, highlight This Computer (Primary), and clickEdit.
15. In the Edit Tableau Server dialog box, setData Engine to 0 and clear theRepositorycheck box. KeepGateway selected. If you want the primary Tableau Server to runnothing but the gateway process (Apache), you can remove the remaining serverprocesses from the primary by entering 0 in each text box.
From a core-based licensing perspective, the gateway process consumes no cores.Configuring the primary Tableau Server to run nothing but the gateway is a usefulstrategy if, for example, you have an 8-core server license and two 4-core workers. You
- 54 -
can run three servers (primary plus two workers), but only the worker servers areconsuming cores.
ClickOK.
16. On the Servers tab, select the first worker, clickEdit, and select theGateway check box.Leave the other settings as-is. ClickOK.
17. Still on the Servers tab, select the second worker and clickEdit.18. SetData Engine to 1 and select theRepository check box.
- 55 -
19. ClickOK.
The Servers tab should now look similar to the following:
20. You can also set up email alerts so that you’re notified of server failures or changes instatus for your data engine and repository processes. To do this, click the Alerts andSubscriptions tab in the Configuration dialog box and follow the steps inConfigureEmail Alerts on page 12.
21. ClickOK to close the Configuration dialog box.
22. Start the server on the primary (it may take a few minutes for your changes to takeeffect). Your system is now configured to provide failover support for the data engineand repository processes. It is also configured for multiple gateways. You can now use aload balancer to ensure the cluster's availability in the event of a gateway failure—and todistribute the cluster's workload.
The Status table on theMaintenance page should look similar to the following:
- 56 -
A light green checkmarkmeans a process is standing by, ready to take over if the activeprocess (dark green checkmark) should fail.
Confirm Failover Externally
Once you add a second server that is running the data engine or repository, you can use theUse external hosts to confirm failover check box on the Servers tab. This option lets youlist one or more computers or websites external to your Tableau Server cluster that will be usedto check the cluster's connectivity status in the event of a failover.
Using an external host or website to confirm failover ismost useful in a two-node TableauServer system like the following:
- 57 -
In the above system, the primary Tableau Server and a worker server are running the activeand standby instances of the data engine and the repository, as well as gateways. The thirdcomputer, external to the Tableau Server cluster is being used as a third point of contact for thetwo gateways. Here's why:When a Tableau server that's running the data engine or therepository loses connectivity with the other nodes, it checkswith a gateway process external toitself (but still within the Tableau Server cluster) to determine which node failed and whetherany standby processes now need to become active. In a two-node cluster, if connectivity is lost,it's not possible to reach that other Tableau gateway process. In these cases, a computer thatisn't running Tableau can be used tomake a simple TCP connection. If the worker server in theabove diagram lost connectivity with the primary but could still connect to the external host, thatwould be the trigger for it to start running the active instances of the data engine and repository.
If the external host or website can't be reached, neither the active nor standby repository willstart, and amessage is written in one of two log files on the servers that are hosting the dataengines:
l tabspawnpg.log—If the external server is accessible when Tableau Server starts, butis not available when the repository starts (or restarts), the error is logged inProgramData\Tableau\Tableau Server\data\tabsvc\logs\pgsql\tabspawnpg.log
or
l tabadmin.log—If the external server is unreachable when Tableau Server starts,
- 58 -
Tableau Server will not start successfully and the error is logged inProgramData\Tableau\Tableau Server\Logs\tabadmin.log.
Example log messages:
2013-11-04 14:42:23.934 -0800 ERROR root: Not "Primary": Noquorum. Cannot reach external failover confirmation host onmyco.example.lan:80 from 10.98.7.65
2013-11-04 14:42:23.945 -0800 ERROR root: Not "Secondary": Noquorum. Cannot reach external failover confirmation host onmyco.example.lan:80 from 10.98.7.65
Add a Load BalancerYou can enhance the reliability of a Tableau Server cluster by runningmultiple gateways andconfiguring a load balancer to distribute requests across the gateways. Unlike the repositoryprocess, which can be active or standby, all gateway processes are active. If one gateway in acluster becomes unavailable, the load balancer stops sending requests to it. The load balanceralgorithm you choose determines how the gatewayswill route client requests.
If you plan to also create a backup primary and that computer will be running a gatewayprocess, be sure to identify that gateway to your load balancer, along with all the othergateways.
Guidelines
Note the following as you configure your load balancer to work with Tableau Server:
l Tested load balancers: Tableau Server clusters with multiple gateways have beentested with Apache and F5 load balancers.
If you are using an Apache load balancer and creating custom administrative views, youneed to connect directly to the Tableau Server repository. You cannot connect throughthe load balancer.
l Tableau Server URL: When a load balancer is in front of a Tableau Server cluster, theURL that's accessed by Tableau Server users belongs to the load balancer, not theprimary Tableau Server.
l X-Forwarded-For and X-Forwarded-Host headers: The Tableau Server UserActivity administrative view displays client IP addresses, among other information. Forthis view to display the IP addresses of clients instead of the cluster's load balancer, theX-Forwarded-For andX-Forwarded-Host headersmay need to be explicitly enabledon the load balancer (some load balancers have it enabled by default, some do not).
l Trusted host settings: The computer running the load balancer must be identified toTableau Server as a trusted host. See the procedure below for how to configureTableau Server.
l Proxy server configurations: The settings used to identify a load balancer to Tableau
- 59 -
Server are the same ones that are used to identify a proxy server. If your Tableau Servercluster requires both a proxy server and a load balancer, bothmust be handled by thesame process, on the samemachine.
Configure Tableau Server to Work with a Load Balancer
You can configure Tableau Server to work with a load balancer by performing the followingsteps.
1. Stop the server.
2. In the Tableau Server bin directory, enter the following command, where name is theURL that will be used to reach Tableau Server through the load balancer:tabadmin set gateway.public.host "name"
For example, if Tableau Server is reached by entering tableau.example.com in abrowser address bar, enter this command:tabadmin set gateway.public.host "tableau.example.com"
3. By default, Tableau assumes that the load balancer is listening on port 80 for externalcommunications. To use a different port, enter the following command, where port_number is the port:tabadmin set gateway.public.port "port_number"
4. Now, enter the following command, where server is the IPv4 address or computername of the load balancer:tabadmin set gateway.trusted "server"
The value for server can be a comma-separated list, for example:tabadmin set gateway.trusted "123.45.67.890, 123.45.67.880,123.45.67.870"
ortabadmin set gateway.trusted "proxy1, proxy2, proxy3"
5. In the next command, you will provide any alternate names for the load balancer, suchas its fully-qualified domain name, any non-fully-qualified domain names, and anyaliases. These are the names a user might type in a browser. Separate each namewitha comma:tabadmin set gateway.trusted_hosts "name1, name2, name3"
For example:tabadmin set gateway.trusted_hosts "lb.example.com, lb,ftp.example.com, www.example.com"
6. Run the config command:
- 60 -
tabadmin config
7. Start the server so the changes can take effect.
Configure a Backup PrimaryBefore you follow the procedures in this topic, follow the steps inConfigure for Failover andMultiple Gateways on page 50. After going through those steps, you have two worker serversthat are providing failover support. Each server is also running a gateway, for which a loadbalancer can be configured. The primary Tableau Server is running a gateway process andlicensing, which is not exposed or assignable as a process. Now that you have redundancy forthe data engine, repository, and gateway, you need to build in redundancy for your primaryTableau Server. You do this by creating a backup of it. While the backup primary needs to belicensed during installation, it does not count as one of the three environments allowable underthe Tableau EULA.
Keep inmind that licensing is checked every 8 hours. If the primary is only running the licensingcomponent, and depending on when the licensing check last occurred, you have up to 8 hoursto bring the backup primary online. During that window of time, the cluster will continue tofunction. For example, if the licensing check occurred 7 hours and 50minutes ago, you have 10minutes. If the licensing check occurred 1minute ago, you have 7 hours and 59minutes. Tosee when the last licensing check occurred, look at the checklicense_lic.log file and other logfiles in the ProgramData\Tableau\Tableau Server\data\tabsvc\logs\licensing folder.
The first procedure below describes how to create a backup of your primary. The secondprocedure walks you through what to do if your current primary fails.
Creating a Backup Primary
Do the following to create a backup primary:
1. Stop the server on your primary Tableau Server.
2. On the primary, open a command prompt as an administrator and navigate to theTableau Server bin directory:
C:\Program Files\Tableau\Tableau Server\8.2\bin
3. Version 8.1.3 and earlier: Enter the following command, where <primary1> is thecurrent primary's IPv4 address or computer name and <primary2> is the backupprimary’s IPv4 address or computer name:tabadmin failoverprimary --primary <primary1> --secondary<primary2>
Version 8.1.4 and later: Enter the following command, using either the computernames for the current and backup primaries (recommended) or all the IPv4 addressesfor the current and backup primaries. If you enter IPv4 addresses, separate each with acomma.
- 61 -
tabadmin failoverprimary --primary "primary1_name,primary2_name"
ortabadmin failoverprimary --primary "primary1_IP,primary2_IP"
For example, if the computer name of the current primary is TABLEAU_SERVER and thecomputer name of the backup primary is TABLEAU_SERVER2, you would enter thefollowing:tabadmin failoverprimary --primary "TABLEAU_SERVER,TABLEAU_SERVER2"
Here's a command example that uses IPv4 addresses. This example assumes that yourprimary (primary1_IP) has a single IPv4 address of 123.45.67.90 and yourbackup primary (primary2_IP) has a single IPv4 address of 123.45.67.89:tabadmin failoverprimary --primary"123.45.67.90,123.45.67.89"
If the primary and backup primary havemultiple IPv4 addresses, enter them all. Forexample:tabadmin failoverprimary --primary"123.45.67.90,123.45.67.91,123.45.67.89,123.45.67.88"
4. Next, create a copy of the primary’s tabsvc.yml file (located inProgramData\Tableau\Tableau Server\config) and put the copy in a temporary locationon your backup primary computer.
The tabsvc.yml file contains server configuration settings. It gets written to when youchange your configuration settings in the Tableau Server Configuration dialog box or viatabadmin. If tabsvc.yml changes, you will need to update the copy of tabsvc.yml on yourbackup primary.
5. On your backup primary, open the tabsvc.yml file and replace the IP address(es) orcomputer name for the primary with the IP address(es) or computer name for thebackup primary (the computer you’re currently on). If the primary is only running thegateway, as described in this procedure, the only line you'll need to edit isworker.hosts. If the primary is running additional processes, replace the primary's IPaddress(es) or namewith the backup primary's anywhere it appears.
- 62 -
6. On your backup primary, install Tableau Server. Use the sameRun As account andconfiguration settings that you used when you ran Tableau Server Setup on yourprimary.
7. After Setup completes, stop the server on the backup primary.
8. Still on your backup primary, enter the following command to disable its Tableau Serverservice:
- 63 -
sc config tabsvc start= disabled
You’ve finished creating a backup primary. See the next set of steps for what to do if yourcurrent primary fails. If you are working in a test environment, this would be a good timeto test your configuration by powering down your current primary to simulate a systemfailure.
Configuring the Backup Primary
Follow this second set of steps in the event of a primary failure. All steps should be performedon the backup primary computer.
1. On your backup primary, use the tabsvc.yml file you edited in step 5 of the previousprocedure to overwrite the locally installed one in ProgramData\Tableau\TableauServer\config.
2. Open a command prompt as an administrator and navigate to the Tableau Server bindirectory:
C:\Program Files\Tableau\Tableau Server\8.2\bin
3. Version 8.1.3 and earlier: Enter the following command, where primary2 is the IPv4address or computer name of your backup primary (soon to be your new primary) andprimary1 is the IPv4 address or computer name of your former primary (soon to beyour backup):tabadmin failoverprimary --primary <primary2> --secondary<primary1>
Version 8.1.4 and later: Enter the following command, using either the computername of your backup primary (soon to be your new primary) or the IPv4 addresses of thebackup primary (soon to be your new primary) and the primary (soon to be your backupprimary). If you enter IPv4 addresses, separate each with a comma.tabadmin failoverprimary --primary "primary2_name,primary1_name"
ortabadmin failoverprimary --primary "primary2_IP,primary1_IP"
For example, if the computer name of the backup primary is TABLEAU_SERVER2 andthe name of the former primary is TABLEAU_SERVER, you would enter the following:tabadmin failoverprimary --primary "TABLEAU_SERVER2,TABLEAU_SERVER"
Here's an example that uses IPv4 addresses. This example assumes that your backupprimary (primary2_IP) has a single IPv4 address of 123.45.67.89 and yourformer primary (primary1_IP) has a single IPv4 address of 123.45.67.90:
- 64 -
tabadmin failoverprimary --primary"123.45.67.89,123.45.67.90"
If the backup primary and former primary havemultiple IPv4 addresses, enter them all.For example:tabadmin failoverprimary --primary"123.45.67.89,123.45.67.88,123.45.67.90,123.45.67.91"
4. Enter the following command:sc config tabsvc start= auto
5. Start the server. Your backup primary is now your primary. When you look at the Statustable on theMaintenance page, you should notice that the IP address or computer namefor the primary has changed:
6. For your former primary to now act as your backup primary, you will need to do thefollowing:
l Use Add/Remove Programs to remove Tableau Server from your former primary.At the end of the Uninstall program you will receive a backup error, which you canignore.
l Delete the Tableau folders under ProgramFiles and ProgramData on your formerprimary.
l Repeat the steps in this topic starting with step 4 under “Creating a BackupPrimary.”
- 65 -
Work with the ServerRefer to the following topics as you use the Tableau Server user interface to administer yourinstallation:
Users and LicensesEveryone who needs to access Tableau Server, whether it's to publish, browse, or administer,must be added as a user. In addition, usersmust be assigned a license level.
UsersEveryone who needs to access Tableau Server—whether it's to publish, browse, oradminister—must be added as a user. If Tableau Server is runningmultiple sites, theAllUsers page is where system administrators do this. Otherwise, if Tableau Server is in singlesite mode, system and site administrators can add users on theUsers page.Default User
Tableau Server automatically creates the "Tableau Software" user account and assigns it oneof the available interactor licenses. This account is used to publish the sample workbooks. Bydefault, this account does not have a password and cannot be used to sign in.
You can either change this account's license level to make the license available for anotheruser (seeChange License Levels on page 84) or, if the server is configured to use theinternal user management system (Local Authentication), you can add a password to theaccount to allow access (seeEdit Users on page 77)
Once you add users, you can edit and delete them, add or remove them from sites, and assignthem license levels and user rights. See the topics below for more information.
Add Users
Both system administrators and site administrators with the correct permissions can add usersfrom theUsers page:
- 66 -
There are two ways you can add users from the Users page: Interactively (as describedbelow), or in batches using the Import command, which relies on a CSV file (described inImport Users from a CSV File on page 70).To add a user:
1. On theUsers page, click theAdd link above the list of users:
2. Enter aUsername.l Local authentication: If the server is configured for local authentication, using anemail address for theUsername is the best way to avoid username collisions (forexample, [email protected] instead of jsmith). After you enter aUsername,clickAdd User.
l Active Directory: If you are adding a user that is from the same Active Directorydomain that the server is running on, you can type theUsernamewithout the
- 67 -
domain. The server’s domain will be assumed.
If there is a two-way trust set up between the server’s domain and anotherdomain, you can add users from both domains. The first time you add a user fromthe “non-server domain,” use the fully-qualified domain namewith the username.Subsequent users can be added using the domain’s nickname. For example,assuming a “non-server domain” ofmybiz.lan, enter the first user from thatdomain as [email protected] ormybiz.lan\user1. The next user can be enteredusing the domain’s nickname, such as user2@mybiz ormybiz\user2.
Note: Be sure not to enter the user’sFull Name in this field as it can cause errorsduring the importing process.
3. Local authentication only, provide the following:l Full Name—Type a display name for the user (e.g., John Smith).
l Password—Type a password for the user.
l Confirm—Retype the password.
4. License Level: Select a license level. See Licenses and User Rights on page 82 andPermissions Reference on page 197 to learnmore.
5. User Rights: Select whether the user can publish workbooks and assign administratorrights. SeeAllow or Deny User Rights on page 86 to learnmore.
6. ClickAdd.
Note for multi-site servers:Site administrators can edit an existing user’s account as long as the user is only amember ofsites that the site administrator also controls. For example, if User Joe is amember of Site Aand Site B and the site administrator is only an administrator of Site B, the site administratorcan’t edit Joe’s Full Name or reset his password.
Add Users to a Site
Once you add a site to Tableau Server, it becomes amulti-site system and what was formerlytheUsers page becomes two pages:All Users andSite Users. As the system administrator,only you can access theAll Users page, which applies to the entire server system. It's the onlyplace where you can add users tomultiple sites all at once, remove users, and if the server isusing local authentication, reset user passwords.
- 68 -
TheSite Users page is an easyway to quickly see which users are on the site you're currentlysigned into. You can add users from here, but theywill only be added to that site.
The following procedure describes how to add users fromAll Users. There are twoapproaches you can take: One at a time (described below) or in batches using the Importcommand, which relies on a CSV file (described in Import Users from a CSV File on page70).
To add a user:
- 69 -
1. From theAll Users page, click theAdd link at the top of the list of users.
2. Enter aUsername:l Local authentication—If the server is using local authentication, using an emailaddress for the username is the best way to avoid username collisions (forexample, [email protected] instead of jsmith).
l Active Directory— If you are adding a user that is from the same ActiveDirectory domain that the server is running on, you can type theUsernamewithout the domain. The server’s domain will be assumed.
If there is a two-way trust set up between the server’s domain and anotherdomain, you can add users from both domains. The first time you add a user fromthe “non-server domain,” use the fully-qualified domain namewith the username.Subsequent users can be added using the domain’s nickname. For example,assuming a “non-server domain” ofmybiz.lan, enter the first user from thatdomain as [email protected] ormybiz.lan\user1. The next user can be enteredusing the domain’s nickname, such as user2@mybiz ormybiz\user2.
Note: Be sure not to enter the user’sFull Name in this field as it can cause errorsduring the importing process.
3. If the server is using local authentication, provide the following:
l Full Name—Type a display name for the user (e.g., John Smith).
l Password—Type a password for the user.
l Confirm—Retype the password.
4. Site Membership—Select which site(s) the user should be amember of. The site youare signed into is selected by default.
5. License Level and User Rights—Select a license level, Admin role, and whether theuser can publish workbooks and data sources. A user who belongs tomultiple sites canhave different license levels and user rights on each site. SeeAbout License Levelson page 82, Permissions Reference on page 197, andAbout User Rights on page
- 70 -
85 to learnmore.
6. ClickAdd User.
Import Users from a CSV File
You can automate the process of adding users by using a CSV file.Requirements
l TheCSV file must be saved in UTF-8 format, with the byte-order mark (BOM).
l Character encodings other than UTF-8, such as BIG-5, must be converted. You can dothis via a “Save As”.
l Do not use column headers. If you use column headers (Username, Password, etc.),Tableau Server will attempt to import them as the literal credentials for the first user inthe file.
l The following two columns are always required:l Username
l Password: If Tableau Server is configured to use Active Directory userauthentication, theremust be a Password column, but the column itself shouldbe empty. If the server is using local authentication, youmust provide passwordsfor new users. See also “Multi-Site Mode andWhere you Import From” for otherinformation.
l TheCSV file can also have the following optional columns, in the order shown below(after the Username and Password columns):
l Full Name
l License Level (Interactor, Viewer, or Unlicensed)
l Administrator (System, Site, Site or None)
l Publisher (yes/true/1 or no/false/0)
l Email Address
l The order of the columns is significant. The first column is treated as Username, thesecond as Password, the third as Full Name, etc., regardless of the columns' con-tents.
Multi-Site Mode andWhere You Import From
If the server is runningmultiple sites and you are a system administrator, there are two pagesfromwhere you can do a CSV user import. Each has different capabilities where existingserver user accounts are concerned.
l All Users page: This page displays if a server is runningmultiple sites and only systemadministrators can access it.
- 71 -
CSV imports from here allow you to update existing server user accounts, in addition toadding new ones. For example, if you do a CSV import that has a new password foreach existing user, their passwordswill be reset.
l
TheSite Users page:
When a system administrator is working from here, they have the same capabilities as asite administrator. Thismeans they can add new user accounts with CSV imports and, if
- 72 -
existing users are part of the import, thePassword and Full Name fieldsmust eithermatch or be left blank. If new passwords or full names are used, the import will fail.
If you are a site administrator on a server with multiple sites, you performCSV user importsfrom theUsers page.
Users can belong tomore than one site on the same server, but theymust use the samecredentials for each site. This becomes important when you're adding users to a site and thoseusersmight already bemembers of a different site. If you try to import a user who alreadyexists, and if the user's credentials in the CSV file don't match the existing credentials, theimport fails for that user.
Note: The issue of credentialsmismatch during import doesn't apply if the server isconfigured to use Active Directory for authentication. In that case, the CSV file shouldnever contain a password, because user passwords aremanaged by Active Directory.
If you're importing users into a site and you think that the usersmight already exist on theserver, you can try leaving the Password column in the CSV file blank.When you import theusers, if a user who is defined in the CSV already exists in another site, the user is added to thesite where you're importing. However, if the user doesn't already exist on the server, the user iscreated, and the CSV import window alerts you that the new user doesn't have a password.You can then use the server environment to assign a password to any user who doesn't haveone.Adding Users from aCSV File
To add users from aCSV file:
- 73 -
1. From theUsers orAll Users page, click the Import link:
2. ClickBrowse, navigate to the file, and clickCheck File:
3. Preliminary results display. To see account-specific information, selectView Details:
4. To continue, click Import Users then clickExit in the final dialog box.
Add Users to a Group
Oneway tomake it easier to manage users is to assign them to groups. That way you canassign permissions to an entire group rather than each individual user. To add a user to agroup, the groupmust already exist. SeeCreate Groups on page 88 for more information.To add a user to a group:
- 74 -
1. On the Admin tab, select the Users page:
If you are the system administrator for amulti-site server, you'll need to do this on a per-site basis using the Site Users page:
2. Select one or more users.
3. Click theGroup + link above the user list, then select a group to add the users to:
- 75 -
View, Edit and Delete Users
Use this topic to learn how to view, edit, and delete Tableau Server users.View Users
If Tableau Server is runningmultiple sites,All Users lists all users on the server system, andSite Users displays all users for the site you’re currently logged into:
Note:By default, this list of users is private and can only be seen by administrators. You canmake thelist of users public by enabling Public User List, in the Settings area of theMaintenance page. Ifthe server is runningmultiple sites, enabling this setting will only show users the names ofusers on their site.
Usersmay be listed acrossmultiple pages. As you select users in the list they are added to aquick list in the upper left corner. The quick list lets you see how many users you have selected
- 76 -
and helps you easily remove users from the selection. Click the "x" button next to the usernamein the quick list to remove someone from the selection.
You can also use theSearch box under Filters on the left to quickly find a specific user in thelist.
Type all or part of the user's name and press Enter. You can use an asterisk (*) character as awildcard in the search. For example, searching for John* will return all names that start withJohn.The Publish Right
Administrators can use the user list to see who can publish and whether that right was setexplicitly or implicitly. If the Publish right was explicitly set, anAllowed (Granted) tooltipappears when you hover over the green checkmark in the Publish column:
- 77 -
Users who can publish because they are an administrator or project leader have an implicitright to publish. In other words, it comeswith their role. AnAllowed (Implicit) tooltip appearswhen you hover over the checkmark:
Edit Users
If the server is configured to use the internal user management system (Local Authentication),you can edit theDisplay Name andPasswordfor users after they have been added. If you aremakingmany changes it is easier to import the changes from aCSV file. SeeAdd Users onpage 65 for details.
To edit user information:
1. Select a single user in the user list.
2. Click theEdit link at the top of the list.
3. Type a new Display Name andPassword into the corresponding text boxes.
- 78 -
4. ClickSubmit.
Note for multi-site servers:Site administrators can edit an existing user’s account as long as the user is only amember ofsites that the site administrator also controls. For example, if User Joe is amember of Site Aand Site B and the site administrator is only an administrator of Site B, the site administratorcan’t edit Joe’s Full Name or reset his password.Delete Users
To delete users:
1. Select one or more users to delete.
2. ClickDelete at the top of the list.
3. ClickYes in the confirmation dialog.
You can only remove a user from Tableau Server if the user does not own any content(workbooks, data sources, etc.). If you use the preceding procedure to delete a user whoowns content, the user will be set to Unlicensed, but not removed.
- 79 -
Your User Preferences Page
The options on your User Preferences page affect your Tableau Server web sessions. Usethem tomanage your subscription settings, specify your start page, change the language andlocale you see in Tableau Server, clear cookies for data connection passwords, or change yourpassword. You can also use this page to quickly browse items that you've published.
To access your User Preferences page, click your username at the top of the page and selectUser Preferences from the drop-downmenu:
Change Your Email Address
If you have a subscription for a Tableau Server view or workbook, the email account thatreceives the subscription is listed on the User Preferences page:
To enter or change the email address that Tableau Server sends subscriptions to, enter thenew email address in theEmail text box, enter it again in theConfirm Email text box, thenselectSet:
Manage Your Subscription Settings
Use the Subscription options to change the schedule for any subscriptions you're receiving.
To change your subscription schedule:
- 80 -
1. Under Schedule, select a different schedule:
2. ClickUpdate.
This is also where you can unsubscribe from a view or workbook. For more information, seeUnsubscribe from a View or Workbook on page 112.Customize Your Start Page
Tableau Server installs withViews as the default start page for all users, but the administratorcan specify a different start page. To figure out what your start page is, clickGo to start page:
You can designate a different start page for yourself by navigating to the server page you want,such asWorkbooks, and selecting theMake this my start page command from the upperright drop-downmenu:
To return to using the start page designated by your administrator, on your User Preferencespage, clickReset to default:
Language and Locale
The Language setting controls the language you see for the Tableau Server user interfaceand Locale affects things in views, such as how numbers are formatted, or which currency isused. Your administrator can configure these settings for all server users, but you can changethem here, just for yourself. If you do change the settings, note that theywill only take effect ifthey are a supported language. See Language and Locale on page 154 to learnmore.After youmake your Language and Locale selections, clickSet.
- 81 -
The next time you sign in, the settings are used for your server sessions.Change Your Password
If the server is configured to use the internal user management system (Local Authentication)instead of Active Directory, you can change your Tableau Server password by clickingChange password. When you click this link you are asked to enter yourCurrent Passwordand theNew Password (twice). After you've typed in the required information, clickChangeto save the changes.
Clear Your Saved Data Connection Passwords
If you access a view or workbook that has a live database connection and requires you toauthenticate, Tableau offers to save your password for you. If you accept, it stores yourcredentials in a cookie. ClickClear All under Saved Data Connection Passwords to removethe cookie from Tableau Server:
Browse Your Published Items
Your user account page lists all of the workbooks, tags, and comments that you've published.Use this page to quickly browse your own activity on the server.
- 82 -
Licenses and User RightsThe license level and user rights you assign to users determine how much they are able to do inTableau Server.
About License Levels
To open the Licenses page, click the Licenses link on the Admin tab:
- 83 -
All users on Tableau Server must be assigned a license level, even if that level is Unlicensed.Tableau Server license levels do not correspond to the Tableau Server named user licensesyou purchased from Tableau (if you are using user-based instead of core-based serverlicensing). Those licenses allow you to have a certain number of users on the server. Licenselevels enable administrators to control how much access users have on the site.
Here are the license levels you can assign:
License Level DescriptionUnlicensed The user cannot sign in to
the server. All users areadded as unlicensed bydefault.
Viewer The user can sign in andsee published views on theserver but cannot interactwith the views. Users withthis level can only be givenpermission to view, addcomments, and view com-ments. They cannot inter-act with quick filters or sortdata in a view.
Interactor The user can sign in,browse the server, andinteract with the publishedviews. It's important to notethat specific views, work-books, and projectsmayhave been added with per-missions that restrict auser's capabilities. Per-mission settings can beedited by the workbookauthor or an administrator.
Guest The guest license level isavailable to allow userswithout an account on theserver see and interactwith an embedded view.When enabled, the usercan load a webpage con-taining an embedded visu-alization without signing in.This option is only available
- 84 -
License Level Descriptionwith a core-based server.
If you have a user-based Tableau Server license, you can review how these levels have beendistributed on the Licenses page:
If you have a core-based Tableau Server license, the Licenses page shows you whether Guestconnections are allowed:
It also shows how many cores you have licensed and how many are in use:
Change License Levels
You typically assign a license level when you create a user. To change the license level for oneor more existing users, follow these steps:
- 85 -
1. On the Admin tab, clickUsers.
2. Select one or more users.
3. Click the License User at the top of the list.4. SelectUnlicensed, Viewer, or Interactor for the selected users.
The License Level column in the list of users is updated to reflect the changes.
About User Rights
In addition to the license level, users' privileges on Tableau Server are also affected by theiruser rights:
User Right DescriptionPublish Allows users to connect to Tableau
- 86 -
User Right DescriptionServer from Tableau Desktop in orderto publish and download workbooksand data sources.
Admin Makes the user an administrator.
There are two types of administrators:Site administrators and systemadministrators.
l Site administrators canmanage groups, projects,workbooks, and dataconnections. By default, siteadministrators can also addusers and assign user rights andlicense levels but a systemadministrator can disable that(seeAdd or Edit Sites on page116).
l System administrators haveall the rights of a siteadministrator, plus they canlicense unlicensed users, controlwhether site administrators canadd users, create additionalsystem administrators, and theycan administer the server itself.This includes handlingmaintenance, settings,schedules, and the search index.
The Admin right can only beassigned to users with theInteractor license level and thePublish right.
Allow or Deny User Rights
You typically assign user rights when you create a user. To change the user rights for one ormore existing users, follow these steps:
- 87 -
1. On the Admin tab, clickUsers.
2. Select one or more users.
3. ClickPublishing orAdmin at the top of the list.4. SelectAllow orDeny to change the Publishing right for the selected user(s).
5. FromAdmin, selectSystem, Site, orNone to change the Admin right for the selectedusers. The Admin and Publish columns in the list of users are updated to reflect thechanges.
Groups and ProjectsGroups and Projects help you organize your workbooks and users on Tableau Server.
- 88 -
GroupsYou can organize Tableau Server users into groups tomake it easier to managemultipleusers. You can either create groups locally on the server or import fromActive Directory. Youcan create andmanage groups on theGroups page, which lists all groups on the server or site,if the server hostsmultiple sites.
Create Groups
Depending on how the server has been configured you can add groups using the internal usermanagement system (local authentication) or you can import fromActive Directory.Create a Local Group
A local group is one that’s created on Tableau Server using the internal user managementsystem. After you create a group you can add and remove users. To create a local group:
1. ClickNew at the top of the list of groups.
2. Type a name for the group and clickAdd Group:
3. ClickReturn to Groups to return to the list of groups.
- 89 -
Create aGroup via Active Directory
Groups can also be imported fromActive Directory. When you import Active Directory groups,amatching group is created on the server and a user is created on the server for eachmemberof the group. Each user is unlicensed and does not have permission to publish. If the useralready exists on the server, he or she is added to the new group and his or her permissionsare not changed. See Licenses and User Rights on page 82 to learnmore about licenselevels and user rights
1. Click Import Active Directory Group at the bottom of the list of groups.
2. Type the name of the Active Directory group you want to import and click Import
3. If you don't know the exact name of the group you can find it by typing all or part of thegroup name into the Search text box. Then clickSearch. You can use the asterisksymbol ( * ) as a wildcard.
4. Select the group from the list of search results.
5. The group name is automatically added to the Import text box. Click Import to add the
- 90 -
group to Tableau Server.
Note: You cannot change the name of groups imported fromActive Directory. Thegroup name can only be changed in Active Directory.
Synchronize an Active Directory Group
At any time, you can synchronize an Active Directory group with Tableau Server so that anynew users in Active Directory are also added to the server. You can synchronize individualgroups or multiple groups at once.
1. On theGroups page, select one or more groups.
2. ClickSynchronize.
If you are adding a group that is from the same Active Directory domain that the server isrunning on you can simply type the group name. In addition, if there is a two way trust setup between the domain the server is using and another domain, you can add groupsfrom both domains. The first time you add a group from a different domain than the onethe server is using, youmust include the fully qualified domain namewith the groupname. For example, domain.lan\group or [email protected]. Any subsequent groups
- 91 -
can be added using the domain's nickname. SeeModify Domain Names on page 10 tolearnmore about managing domain names.
Removing Users
When you remove a user fromActive Directory then synchronize with that user's group onTableau Server, the user is:
l Removed from the Tableau Server group you synchronized
l Placed in the All Users group in Tableau Server
l Unable to sign in to Tableau Server
Because the user still remains on the server, as the administrator, you can audit and reassignthe user's content before removing their account completely. The user will not be able to sign into the server. To fully remove the user from Tableau Server you need to do the following:
l Unlicense the user's account (if Tableau Server is using user-based licensing)
l Delete the user from Tableau Server's All Users page
Delete Groups
You can delete any group from the server. When you delete a group, the users are removedfrom the group but they are not deleted from the server.
1. On theGroups page, select one or more groups to delete.
2. ClickDelete above the groups list:
ProjectsA project is a collection of related workbooks. As the administrator, there are two placeswhereyou will seeProjects listed: under theContent tab and under theAdmin tab. If you want tocreate new projects, assign permissions, or delete projects, use theProjects page under theAdmin tab:
- 92 -
While only administrators can create new projects, users and groups can be assigned theProject Leader permission. This permission lets a user or group specify project permissionsandmove workbooks into projects. See the topics below for procedures andmore informationon working with projects:
Add Projects
To add one or more projects:
1. Click theAdd link.
2. Type a name and description for the project and clickAdd. You can include formatting
- 93 -
and hyperlinks in the project description.
Move Workbooks into Projects
All workbooksmust be in a project. By default, workbooks are added to theDefault project.After you've created your own projects you canmove workbooks from one project to another.You canmove workbooks into projects if you have an Interactor license level and at least one ofthe following is true:
l You have been given permission toWrite to the project.
l You have been given Project Leader permission for the project.
l You have been granted the Admin right.
Tomove a workbook into a project:
- 94 -
1. Select one or more workbooks and click theMove link at the top of the list of workbooks.
2. Select a project to move the workbook into.
Because all workbooksmust be part of a project, you can remove a workbook from aproject bymoving it to the Default project. Each workbook can only be part of a singleproject.
Delete Projects
Only administrators can delete projects. When you delete a project, all of the workbooks andviews that are part of the project are also deleted from the server. To delete a project:
1. Select the project in the project list.
2. ClickDelete above the Projects list.
- 95 -
3. ClickYes in the confirmation dialog box.
TheDefault project cannot be deleted.
Schedule Refreshes & SubscriptionsExtract refreshes and subscription deliveries are tasks performed by Tableau Server, andschedules control when those tasks are run.
As the server administrator you have the highest level of control over server tasks andschedules, however, there are two types of tasks that Tableau Server users can schedule.Workbook authors can schedule extract refresheswhen they publish a workbook or a datasource with an extract, and Tableau Server users can subscribe to views, which are deliveredon a schedule. As the administrator, you can adjust an extract or subscription schedule, createnew schedules and refresh tasks, and delete them. You also control whether workbookauthors are allowed to schedule (seeEnable Scheduling on the next page), and you are incontrol of whether the server is configured to send subscriptions (seeManage Subscriptionson page 104). Any changes youmake to an extract’s schedule are reflected in the TableauDesktop Schedule dialog box the next time the author publishes. Similarly, if you create a newsubscription schedule or delete an existing one, it's reflected in the schedule choices a TableauServer user seeswhen they subscribe to a view.
See the topics below for more information:
About Extracts and SchedulesTableau Desktop allows authors to create a data extract, which is a copy or a subset of datafrom the original data source.Workbooks that use data extracts are generally faster than thosethat use live database connections because the extracted data is imported into Tableau's built-in, fast data engine. Extracts can also increase functionality. After a workbook or a data sourcewith an extract has been published, the extract resides on Tableau Server.
- 96 -
Refreshing extracts directly on Tableau Server:
l Web browser: As the administrator, you can change or reassign extract refreshschedules, regardless of whether a workbook or data source with an extract was given arefresh schedule at the time it was published. Any scheduling changes the site'sadministrator makes in Tableau Server are reflected in the Schedule dialog box inTableau Desktop when the workbook or data source is published again.
You can also refresh an extract immediately, using theRun Now option. SeeManageRefresh Tasks on page 100 andCreate or Modify a Schedule on the next page fordetails. Note that before you can create refresh schedules youmust enable schedulingon the server. SeeEnable Scheduling below to learnmore.
l tabcmd command line utility: The tabcmd command line utility provides arefreshextracts commandwhich you can use from the command line orincorporate into your own script. SeeAutomate Refresh Tasks on page 102 for moreinformation.
Refreshing extracts from Tableau Desktop:
l At publish time: When an author publishes a workbook or data source that uses anextract, that author can assign it to a recurring refresh schedule on Tableau Server. Therefresh can be a full refresh or an incremental refresh. Incremental refreshes reference acolumn in the extract that has a data type of date, date/time, or integer; such as atimestamp. Tableau uses this column to identify new rows that need to be added to yourextract. See Refreshing Extracts and Schedules in the Tableau Desktop help for moreinformation.
l User interface: You can use theRefresh from Source,Add Data From File, andAdd Data From Data Source options in Tableau Desktop to upload an addition to orrefresh an extract on Tableau Server. Youmaywant to do this if Tableau Server doesn'thave sufficient credentials to refresh data from the original data source. See UpdatingExtracts on Tableau Server in the Tableau Desktop online help for details on how toupload.
l Data Extract command line utility: The Data Extract command line utility installs withTableau Desktop. You can use it to upload an addition to an extract on Tableau Serveror refresh it. See Tableau Data Extract Command Line Utility in the Tableau Desktoponline help for more information on how to upload.
Enable SchedulingBefore you can schedule an extract refresh, schedulingmust be enabled on the server. Afteryou enable scheduling, you can add workbooks and data sources to schedules, create and editschedules, manage scheduled tasks, and change schedule settings to allow publishers toassign workbooks to schedules. This setting does not affect scheduling for subscriptions.
To enable scheduling, select theScheduling checkbox under Settings on the ServerMaintenance page:
- 97 -
Because database passwordsmay be required to refresh the extract, youmust enableEmbedded Credentials in order to allow scheduling.
Create or Modify a ScheduleThe Schedules page shows a list of schedules, including their name, type, what they're for(scope), number of tasks, behavior (concurrent or serial processing), and when they arescheduled to run.
1. To create a new schedule, clickNew:
2. Tomodify an existing schedule, select it then clickModify:
3. Specify a descriptiveName for the schedule (e.g., Every SaturdayMorning, End of the
- 98 -
Month).
4. Choose aSchedule scope, which is what the schedule will handle—either extractrefreshes or delivering subscriptions.
5. Optionally define aDefault Priority from 0 to 100. This is the priority that will beassigned to the tasks by default. If two tasks are pending in the queue, the one with thehighest priority runs first. SeeManage Refresh Tasks on page 100 to learnmore aboutmodifying a task's priority.
6. Choose whether the jobs in the schedule will run at the same time (concurrently, thedefault) or one after the other (sequentially).
7. Finish defining or editing the schedule. You can define an hourly, daily, weekly, ormonthly schedule.
- 99 -
8. ClickCreate Schedule if it's a new schedule or Save Schedule if youmodified anexisting schedule.
Add a Data Source or Workbook to a ScheduleOnce you've enabled scheduling you can add a workbook to a schedule from theWorkbookslist, or you can add a data source to a schedule from the Data Sources list. By default TableauServer has three built in schedules for refreshing extracts. You can also create your own. SeeCreate or Modify a Schedule on page 97 for details.
1. If you are scheduling a workbook for an extract refresh, select one or more on theWorkbooks page and clickScheduled Tasks:
If you are scheduling a data source for an extract refresh, select one or more on the DataSources page and clickScheduled Tasks:
2. Select eitherAdd Full Refresh orAdd Incremental Refresh, then select a schedulefrom the list:
- 100 -
Add Full Refresh is only available if the selected data source connects to an extract.Add Incremental Refresh is only available if the selected data source connects to anextract data source for which you've defined an incremental refresh. Tableau Servercannot refresh data sources that connect to local file data sources on amapped drive.Update the connection to use the full path to the data source.
Manage Refresh TasksThe Tasks page displays all the full and incremental extract refresh tasks being handled by theserver. System and site administrators can use this page to change a task's priority, move it todifferent schedule, run it, or delete it. You can open the Tasks page by clicking Tasks on theAdmin tab:
Edit a Task's Schedule
Move an extract refresh task from one schedule to another by doing the following:
- 101 -
1. On the Tasks page select one or more tasks tomodify.
2. ClickEdit Schedule. Select a new schedule from the list of schedules:
You can also delete and run tasks by selecting one or more tasks in the list and selecting anoption on the toolbar.
Run a Task Now
You can force an immediate refresh of a task, such as an extract refresh task, using theRunNow option.
1. On the Tasks page, select a task to run.
2. ClickRun Now.
Change a Task's Priority
To change the priority of an extract refresh task:
1. On the Tasks page select one or more tasks tomodify.
2. ClickEdit Priority.
- 102 -
3. Type a new priority from 0 to 100 and clickSubmit.
Automate Refresh Tasks
You can associate extract refresh taskswith schedules in Tableau Server to automaterefreshing data extracts. You can also automate extract refreshes using tabcmd, a commandline utility that ships with Tableau Server and can be installed on a separate computer fromTableau Server. In particular, you can use the refreshextracts command in combinationwith other commands in your own script. For example:tabcmd login - http://mytabserver -u jsmith -p P@ssw0rd!refreshextracts --datasource salesq4
Handle Extract Refresh Alerts
If scheduled extract refreshes did not succeed, Tableau displays an Alertsmenu in the upperright corner:
You will see the Alertsmenu only if an extract refresh failed and you are:
l A system or site administrator.
l The author of the workbook or data source that couldn’t be refreshed.
l The author of a workbook that connects to a data source that couldn’t be refreshed.
When you open the Alertsmenu you can seemore information about the refresh failure(s):
- 103 -
When aData source is listed as Embedded it means that the data source definition (whichincludes things like the data source credentials or the database name) is embedded, orresides, within the workbook itself, originally created in Tableau Desktop.
When a data source name or workbook name is listed as theData source (for example,Datasource: sales_data), it means that the data source is a Tableau Server data source. The datasource definition resides on Tableau Server.
In the Data window, you can identify workbooks or data sources that were originally created inTableau Desktop. A Tableau icon instead of a database icon is displayed next to the datasource name:
- 104 -
Resolving Extract Refresh Problems
You can resolve some extract refresh problems by clicking theEdit connection info link in thealert, and then entering themissing information, and clickingSave:
If the problem cannot be corrected by editing the data connection, you will need to resolve it inTableau Desktop and republish the workbook.
Tip: Administrators can edit data connections at any time on theData Connections page,accessible from theAdmin tab.
Manage SubscriptionsA subscription is a regularly scheduled email delivery of a Tableau Server view or workbook tosubscribed users. When subscribers click the snapshot of the view or workbook in their email, itopens on Tableau Server.
To access information about each subscription, such as the subscriber’s email address andname, the name of the view, and the delivery schedule, clickSubscriptions on the Admin tab.
Requirements
For Tableau Server users to receive subscriptions, the following things need to be in place:
l Email settings configuration: As the system administrator, you configure the basicSMTP server settings for subscriptions on theAlerts and Subscriptions tab in theConfiguration dialog box, which displays during Setup. This is the "from account"Tableau Server uses to email subscriptions to server users. You can access this tabafter Setup aswell. SeeReconfigure the Server on page 22 andConfigure EmailSubscriptions on page 13 for steps.
- 105 -
l Credentials embedded or not required: FromTableau Server's perspective, asubscription includes a workbook, data, and a schedule. To deliver the data piece,Tableau Server needs to be able to access the data with no end-user involvement. Thiscan be accomplished by using either a workbookwith embedded database credentials,a Tableau Server data source, or by using data that doesn't require credentials, such asa file that's included with the workbook at publish time.Workbooks that prompt forcredentials for live database connections can't be subscribed to.
l User requirements: If a user can see a view or workbook onTableau Server and it hasthe subscription icon ( ) in the upper right corner, he or she can subscribe to it. Theability to see a view or workbook is controlled by theView permission. A user must alsohave an email address. If Tableau Server doesn't already have an email address for asubscribing user, it prompts for one at subscription sign-up time. Users can change theirdelivery options, unsubscribe, or update their email address on their User Preferencespage.
l No trusted authentication: If Tableau Server is configured for trusted authentication,subscriptions are disabled. Trusted authentication, in combination with Tableau's LocalAuthentication, creates a "sign-in free" yet authenticated experience for end-users. Tocreate this same experience and use subscriptions, use Active Directory (with Enableautomatic login) as the user authentication type instead. You choose the userauthentication type during Setup. SeeConfigure the Server on page 7 for details.
Additional Subscription Settings
As long as subscriptions are configured on theAlerts and Subscriptions tab and TableauServer is using its default settings, server users can subscribe to the views and workbooks theysee. To prevent users from subscribing or to customize their subscription experience, here'swhere to go:
l Sites page: By default, subscriptions are enabled for every site, but you can use theSites page to disable subscriptions on a per-site basis or to customize it. For exampleyou can enter a custom From address for subscriptions instead of the one you specifiedin the Configuration dialog box. You can also create your own footer for the subscriptionemails your users receive.
l Schedules page: Your users will need at least one subscription schedule to choosewhen they subscribe. Tableau provides two by default. As the system administrator, youcan create additional schedules or remove the default ones. SeeCreate or Modify aSchedule on page 97 for details.
l Subscriptions page: This page lists all the subscriptions on the server or, if you're asite administrator, on the site. System administrators can use this page to change aserver user's subscription schedule or delete their subscription. See the topics below fordetails.
For steps on how to test whether you've configured subscriptions correctly, see Test YourSubscription Configuration on the next page. If you're experiencing an issue withsubscriptions, see Troubleshoot Subscriptions on page 390.
- 106 -
Delete a Subscription
To delete a subscription, select the subscription you want to remove and clickDelete:
Edit a Subscription Schedule
To change the schedule for a subscription, select the subscription, clickEdit Schedule andselect a schedule:
Test Your Subscription Configuration
As the administrator, you can test whether you've correctly configured subscriptions by doingthe following:
1. Subscribe to a view.
2. On the Schedules page, select the schedule that contains your subscription.
3. ClickRun Now:
- 107 -
4. In a few moments, your subscription should appear in your email inbox.
Troubleshoot Subscriptions"The view snapshot in this email could not be properly rendered."
If you receive a subscription with this error message, there could be several reasons:
l Missing credentials: Some views are published with embedded credentials.Youmayreceive the above error if the embedded credentials are now out-of-date, or if the viewwas republished without the embedded credentials.
l Database temporarily down: If the view has a live database connection and thedatabase was temporarily downwhen the subscription was being generated, youmightreceive the above error.
l Background process timeout: By default, the background process that handlessubscriptions times out after 30minutes. In themajority of cases, this is plenty of time.However, if the background process is handling an extraordinarily large and complexdashboard, that may not be enough time. You can check theBackground Tasks onpage 159 admin view to see if that's the case. To increase the timeout threshold, use thetabadmin option subscriptions.timeout.
Can't Subscribe
If you can see a view on Tableau Server and it has a subscription icon ( ) in the upper rightcorner, you can subscribe to it.
Two things need to be in place for you to subscribe to a view: Tableau Server needs to becorrectly configured (described inManage Subscriptions on page 104) and the view you'resubscribing tomust either have embedded credentials for its data source or not rely oncredentials at all. Examples of the latter include a workbook that connects to an extract that isn'tbeing refreshed, or a workbookwhose data is in a file that was included with the workbook atpublish time. Embedding credentials is a step that happens in Tableau Desktop (see theTableau Desktop help for details).NoSubscription Icon
It's possible to see a view on Tableau Server but be unable to subscribe to it. This happens forviewswith live database connections, where you’re prompted for your database credentialswhen you first click the view. A subscription includes a view (or workbook), data, and a
- 108 -
schedule. To deliver the data piece, Tableau Server either needs embedded databasecredentials or data that doesn't require credentials. Where live database connections areconcerned, Tableau Server doesn't have the credentials, only the individual users do. This iswhy you can only subscribe to views that either don’t require credentials or have themembedded.
Youmay also be able to see a view but be unable to subscribe to it (no subscription icon) ifTableau Server is configured for trusted authentication. See Subscription Requirements formore information.Receiving Invalid or "Broken" Subscriptions
If you configured subscriptions on test or development instances of Tableau Server in additionto your in-production instance, disable subscriptions on your non-production instances.Keeping subscriptions enabled on all instances can result in your users receiving subscriptionsthat appear to be valid, but which don't work, or receiving subscriptions even though they'veunsubscribed from the view or workbook.Subscriptions not Arriving ("Error sending email. Can't send command to SMTP host.")
Youmay see the above error inWindowsEvent Viewer if subscriptions appear to be sent(according to theBackground Tasks on page 159 admin view), yet subscriptions aren'tarriving, and your SMTP server is using encrypted (SSL) sessions. Subscriptions are onlysupported for unencrypted SMTP connections. The solution is to use an unencrypted SMTPserver.Custom Scripts not Working after Upgrade to 8.1
To support better sessionmanagement, starting with version 8.1, a hash tag (#) was added tothe end of view URLs. If you had custom subscriptions scripting that generated views as PDFsor PNGs youmay need to update your scripts to allow for the hash tag.
For example, prior to version 8.1, view URLswere like this:http://tableauserver/views/SuperStore/sheet1 and you could generate a viewas a PNGby adding .png to the end of the URL, such as:http://tableauserver/views/SuperStore/sheet1.png. Starting with version8.1, view URLs are like this:http://tableauserver/views/SuperStore/sheet1#1. To generate a PNG, add.png before the hash tag. For example:http://tableauserver/views/SuperStore/sheet1.png#1
Subscribe to Views
If you can see a view on Tableau Server and it has a subscription icon ( ) in the upper rightcorner, your administrator has configured subscriptions for your site and you can subscribe tothe view. Thismeans that, on a regular interval, you can have a snapshot of the viewautomatically delivered to your email inbox—without having to sign in to Tableau Server. Youcan also subscribe to workbooks. Instead of receiving a single view, you receive every view inthe workbook in a single email. You can unsubscribe to subscriptions you no longer want toreceive. See below for details.
- 109 -
You can change your subscription settings on your user preferences page. For moreinformation, seeManage Your Subscription Settings on page 79.
Note: If a dashboard size is set toAutomatic, the image included in the subscriptionemail is fixed at 800 pixels by 600 pixels.
Subscribe to a View
To subscribe to a view or workbook:
1. Select theViews orWorkbooks page:
2. Click a view or workbook.
3. Click the subscription icon in the upper right corner:
- 110 -
4. If your Tableau Server account hasn't already been associated with an email address,you are prompted to provide one. Enter your email address and clickNext.
You can change the email address a subscription is sent to. For details, seeChangeYour Email Address on page 79.
5. In the next dialog, select a subscription schedule. By default, Tableau Server provides aweekdaymornings schedule and aMondaymorning schedule. The Tableau Serveradministrator can also create custom subscription schedules.
- 111 -
6. Next, choose whether you want to subscribe to a single view (This Sheet) or the entireworkbook (Sheets in Workbook) and clickSubscribe.
7. Later, when you receive the subscription by email, click the snapshot of the view and itopens on Tableau Server:
- 112 -
Unsubscribe from a View orWorkbook
To unsubscribe from a view or workbook:
1. Open your User Preferences page on Tableau Server by clicking the link at the bottom ofa subscription email:
- 113 -
You can also open your User Preferences page from the Tableau Server drop-downmenu:
2. Next to the view you want to unsubscribe from, select theUnsubscribe check box.
- 114 -
You can also change your subscriptions here. For more information, seeManage YourSubscription Settings on page 79.
3. ClickUpdate.
SitesUse the Sites page to create independent sites for different organizations or groups on a singleserver system. Each site’s workbooks, data, and user lists are isolated from those of othersites. As the system administrator, only you can see every site and perform actions such ascreating sites andmaking system-wide changes. See the topics below for more information:
Work with SitesThe topics below describe aspects of working with multiple sites such aswhich type ofauthentication is used, aswell as things you should know about user licenses, andadministrator roles.
Authentication and Sign-In Credentials
All sites on a server use the same Server Run As account and user authenticationmode. Youchoose both of these settingswhen you install Tableau Server. SeeGeneral on page 8 formore information.
Users who belong tomore than one site on the same server system use the same credentialsfor each site. For example, if Jane Smith has a username of jsmith and a password of“MyPassword” on Site A, she uses those same credentials on Site B.When she signs intoTableau Server, she’ll be able to choose which site she wants to access.
The Default Site
To help you transition smoothly from a single- to multi-site server system, Tableau Serverinstalls with a site namedDefault. If you’re running in single-site mode, you don’t need toexplicitly use Default, it happens automatically. However, if you add one or more sites, Defaultbecomes one of the sites you can sign in to when you sign in to Tableau Server. Default differsfrom sites that you add to the system in the following ways:
- 115 -
l It can never be deleted but, just like sites that you add, it can be renamed.
l It stores the samples and data connections that ship with Tableau Server.
l TheURL used for Default has no corresponding web folder named “default”. Forexample, the URL for a view named Profits on a site named Sales ishttp://localhost/t/sales/views/profits. The URL for this same view onthe Default site would be http://localhost/views/profits.
The Site and System Administrator Roles
There are two types of administrators in Tableau Server, system administrators and siteadministrators. System administrators can control whether site administrators can add andremove users in the Add New Site (or Edit Site) dialog box:
IfOnly system administrators is selected, site administrators cannot add or remove siteusers. However, they can still manage groups, projects, workbooks, and data connectionswithin their site. IfBoth system and site administrators is selected (the default), siteadministrators can do all of the above, and add or remove users.
Licensing and User Limits
Users can belong tomultiple sites, with different user rights and license levels on each site. Auser who belongs to several sites, however, does not need a license for each site. Each serveruser only needs one license.
System administrators can use theMaximum site users <n> setting to specify a user limit fora site. Only licensed users are counted; system administrators are excluded. For example, if asite has 90 licensed users, 20 unlicensed users, and one system administrator, the user countis 90. IfMaximum site users is set to 100, 10more licensed users can be added.
- 116 -
Add or Edit SitesIf you are a system administrator, you can add a site to Tableau Server, or edit an existing one,by doing the following:
1. ClickSites underAdmin, and then clickAdd.
Or, if you are editing a site, select the site you want to change and clickEdit. If you havenot added sites to Tableau Server, there will be just a single site to select: Default.
2. Enter aSite name andSite ID for the site (if you are editing the Default site, you cannotchange theSite ID):
The “t” in the URL (for example, http://localhost/t/wsales) cannot be changed. In multi-site server systems, it appears in the URL for sites other than the Default site.
3. Workbooks, extracts, and data sources all consume storage space on the server. SelecteitherNo limit orQuota, and enter the number of GB you want as a limit. If you set aquota and the site exceeds it, publishers will be prevented from uploading new contentuntil the site is under the limit again. System administrators can trackwhere the site isrelative to its quota using theStorage Quota and% Quota Used columns on the Sitespage.
- 117 -
4. Next, select whether only you, the system administrator, can add and remove users(Only system administrators) or if it can be done by both types of administrators(Both system and site administrators).
If you are allowing site administrators to add users, specify how many users they canadd to the site by selecting one of the following:
l Up to server capacity: For a server with user-based licensing, the limit is thenumber of available server seat licenses. For a server with core-based licensing,there is no limit to the number of users that can be added.
l Maximum site users <n>: Allows a site administrator to add users up to a limityou specify. SeeWorking with Sites for information on licensing and user limits.
5. SelectAllow performance recording to permit your site users to collect metrics onhow workbooks perform, such as how quickly they load, etc.
In addition to having this check box selected for the site, to initiate recording, usersmustadd a parameter to the workbook's URL. SeeCreate a Performance Recording onpage 240 for more information.
6. LeaveAllow web authoring for this site selected or clear it to disable authoring onthe server completely.
Disabling web authoringmeans that users cannot edit published workbooks from theserver web environment. To update a workbook published to the server, a TableauDesktop user must re-publish it. SeeExample: Disable Web Authoring on page 212for more information.
7. Under Site Subscription Settings, keepEnable subscriptions selected if you want siteusers to be able to subscribe to views. This option is only visible if you have alsoconfigured subscription settings in the Configuration dialog box.
- 118 -
You can also enter a custom From address for the subscriptions.While the addressyou enter should use valid email address syntax (such as [email protected] ornoreply@sales),Tableau Server does not require it to correspond to a real emailaccount (some SMTP serversmay require it to be an actual address, however).
8. ByEmail footer, selectCustom and enter any text you want to appear above theTableau Server URL in subscription footers. For example, if you enter this text:
The email footer will look similar to the following:
9. ClickOK.
If you are adding your first site to Tableau Server, the Admin tab changes.Users is now AllUsers, because it pertains to all users on the server, and aSite Users category appears.
- 119 -
Site Availability
TheAvailability option for a site allows a system administrator to suspend or activate a site. Asite can become suspended or locked due to a site import failure, or because a systemadministrator chooses to suspend the site for a period of time.
When a site is suspended, the only Tableau Server user who can access it is the systemadministrator. Only the system administrator can activate the site to make it available again.To suspend or activate a site
1. ClickSites underAdmin, and then select a site.2. ClickAvailability, and then clickActive or Suspended.
Add Users to a SiteOnce you add a site to Tableau Server, it becomes amulti-site system and what was formerlytheUsers page becomes two pages:All Users andSite Users. As the system administrator,only you can access theAll Users page, which applies to the entire server system. It's the onlyplace where you can add users tomultiple sites all at once, remove users, and if the server isusing local authentication, reset user passwords.
- 120 -
TheSite Users page is an easyway to quickly see which users are on the site you're currentlysigned into. You can add users from here, but theywill only be added to that site.
The following procedure describes how to add users fromAll Users. There are twoapproaches you can take: One at a time (described below) or in batches using the Importcommand, which relies on a CSV file (described in Import Users from a CSV File on page70).
To add a user:
- 121 -
1. From theAll Users page, click theAdd link at the top of the list of users.
2. Enter aUsername:l Local authentication—If the server is using local authentication, using an emailaddress for the username is the best way to avoid username collisions (forexample, [email protected] instead of jsmith).
l Active Directory— If you are adding a user that is from the same ActiveDirectory domain that the server is running on, you can type theUsernamewithout the domain. The server’s domain will be assumed.
If there is a two-way trust set up between the server’s domain and anotherdomain, you can add users from both domains. The first time you add a user fromthe “non-server domain,” use the fully-qualified domain namewith the username.Subsequent users can be added using the domain’s nickname. For example,assuming a “non-server domain” ofmybiz.lan, enter the first user from thatdomain as [email protected] ormybiz.lan\user1. The next user can be enteredusing the domain’s nickname, such as user2@mybiz ormybiz\user2.
Note: Be sure not to enter the user’sFull Name in this field as it can cause errorsduring the importing process.
3. If the server is using local authentication, provide the following:
l Full Name—Type a display name for the user (e.g., John Smith).
l Password—Type a password for the user.
l Confirm—Retype the password.
4. Site Membership—Select which site(s) the user should be amember of. The site youare signed into is selected by default.
5. License Level and User Rights—Select a license level, Admin role, and whether theuser can publish workbooks and data sources. A user who belongs tomultiple sites canhave different license levels and user rights on each site. SeeAbout License Levelson page 82, Permissions Reference on page 197, andAbout User Rights on page
- 122 -
85 to learnmore.
6. ClickAdd User.
Delete SitesSystem administrators can delete sites that have been added to Tableau Server. Deleting asite also removesworkbooks and data sources that were published to the site, as well asusers. If a user belongs to additional sites, theywill not be removed. To permanently remove auser, you need to use the All Users page.
To delete a site:
1. Open the Sites page under Server:
2. Select the site you want to remove and clickDelete:
- 123 -
3. ClickYes in the confirmation dialog box that appears.
Import or Export a SiteYou can provision a new Tableau Server site by exporting an existing site to a file and importingthe file into a new site. The site you export is called the source site. The site into which youimport is called the target site.
The source site can come fromTableauOnline, which is a cloud-based installation of TableauServer that's hosted by Tableau, or it can come from a Tableau Server deployment that youadminister.When you import a site, all of the source site's resources—including workbooks,projects, data sources, users—comewith it. The import also includes any permissions,subscriptions, or user favorites lists that were created. All site-specific settings from the sourcesite (including site quota, subscription and web authoring settings) are preserved in the targetsite.
Before you export...
Before you export a site, note the following:
Delete unused items:Make sure the source site contains only what you want to import.Delete any unused workbooks, projects or data sources.
Remove unused users:Confirm that all users are licensed and remove anywho no longerrepresent actual users. Any user you export from the source site must be imported to the targetsite. You can't remove users during the import.
Create user accounts on the target server: The site import process assigns users to atarget site. The usersmust already have user accounts on the target server system. If you areexporting one site into another on the same Tableau Server, you have all the user accountsyou need. If you are exporting a site from TableauOnline or from a different Tableau server,youmust create user accounts on the target server before you can perform the import.
Check user authentication:User authentication is a server-wide setting and all sites on aserver must use the same setting. You can export from and import to servers that are using
- 124 -
different user authenticationmethods, but you will need tomodify themapping files used for theimport. This step is built into the import process and described inVerify the Site's Mappingson page 126. Because TableauOnline sites use a custom user authenticationmethod,exporting from a TableauOnline site requires edits to the user-specificmapping files. Thisensures a clean import, regardless of how the target server is configured.
Check schedules: The Schedules page on Tableau Server lists the default schedules youcan use for extract refreshes and schedules:
Refreshes and subscriptions assigned to default schedules on the source site will beautomaticallymapped to the same schedules on the target site. If the source site has customschedules, they are imported to the target site and can optionally be renamedwhen you editthemapping files.
Configure the target server to deliver subscriptions: Subscriptionswill be imported tothe new site, but youmust configure the target server to deliver the subscriptions, if it isn'talready configured. For more information, seeAlerts and Subscriptions on page 12.Create or identify the target site: Before you can import a site file, youmust already have atarget site on Tableau Server. Anything that exists in the target site that does not also exist inthe source site will be removed during the import. Because of this, an empty site isrecommended. For more information about creating or making changes to sites, see Add orEdit Sites.
Locate Site IDs: The commands you use to export or import a site require a site ID as aparameter. A site ID uniquely identifies a site to Tableau Server. When you are signed in to asite, the site ID is immediately after the t/ in the URL:
Export a Site
There's no need to stop Tableau Server during the export or import process. To export a site:
1. Open a command prompt as an administrator and navigate to the bin directory onTableau Server. For example:
C:\Program Files\Tableau\Tableau Server\8.2\bin
- 125 -
2. Type the following command:
tabadmin exportsite <site ID> --file <filename or path>.
For example, to export a site with site IDwsales to the following file C:\sites\exported_sites\sales_export.zip, type the following:
tabadmin exportsite wsales --file C:\sites\exported_sites\-sales_export.zip
For examples of other options you can use with the exportsite command, seeexportsite on page 347.
During the export, Tableau Server locks the site.
Import a Site
If you don't already have a target site for the import, create one. See Add or Edit Sites for steps.
Importing a site is a three-step process. First, you run the tabadmin importsitecommand to generate the files that will be imported; next, you verify files that show how the sitewill be imported; and finally, you run the tabadmin importsite_verified command tofinish the import.
Before you begin, you will need the exported site file and the site ID for the target site. The siteID for the Tableau Server default site is ""(double quotationmarks, no space). If you arerunning commandswithinWindowsPowerShell, delimit the Default site double quoteswithsingle quotes ('""').
While there's no need to stop Tableau Server during the import process, the site receiving theimport will be locked until the import completes.Start a Site Import
To start a site import:
1. Open a command prompt as an administrator and navigate to the bin directory onTableau Server. For example:
C:\Program Files\Tableau\Tableau Server\8.2\bin
2. Type the following command:
tabadmin importsite <site ID> --file <filename or path>
where <site ID> is the site ID of the target site and <filename or path> is thefull path to the exported site file.
For example, to import the file C:\sites\exported_sites\sales_export.zip into a site withthe site ID esales, type the following:
tabadmin importsite esales --file C:\sites\exported_sites\-sales_export.zip
- 126 -
For examples of other options you can use with the importsite command, seeimportsite on page 349.
3. After you enter the command, themapping files for you to verify are placed inProgramData\Tableau\Tableau Server\data\tabsvc\temp\import_<site ID>_<datetime>\mappings. Note this location for the next procedure.
Verify the Site's Mappings
Themapping files that are generated after you initiate a site import with the importsitecommand show you how the site's resourceswill be assigned once the import is complete.Items that Tableau Server was unable tomap, and which need editing, aremarked in the CSVfiles with questionmarks (???). Before you can run the final importsite_verifiedcommand youmust change the questionmarks so that they represent valid assignments onthe target site.
You can't add or remove users as part of your changes. All usernames for the users thatyou import must already exist on the target server.
To verify a site'smapping files:
1. Navigate to the directory that was displayed after you entered the importsitecommand:
2. UsingMicrosoft Excel (recommended) or a text editor, open each CSV file in themappings folder.
Each file shows how items from the source site will bemapped, or handled, once theimport to the target site is complete.
3. Verify that themappings are correct. Replace any entry consisting of questionmarks( ???) with a valid value. Use this table as a guide:
CSV file name Columntitle
Can itbeedite
Description
- 127 -
d?map-pingsDomainMapperForGroups
source_name
No A user group name on thesource site.
source_domain_name
No The user authenticationtype on the source site:either local (for LocalAuthentication) or a domainname (for Active Directory).
target_domain_name
Yes* The user authenticationtype on the source site:either local for LocalAuthentication, or a domainname (such asexample.com orexample.lan) for ActiveDirectory.
*Do not edit the target_domain_name value forAll Users. Keep its value oflocal, even if your targetserver is configured forActive Directory userauthentication. TheAllUsers group is a specialdefault user group thatmust exist on everyTableau Server.
mappingsScheduleMapper source_name
No The names of custom anddefault extract or sub-scription schedules on thesource site.
source_scheduled_action_type
No The type of schedule, eitherExtract, for extractrefreshes, orSubscription, for sub-scription deliveries on thesource site.
target_name
Yes The names of customschedules on the targetsite. You can edit this value.For example, if the sched-ule is named FridayUpdate on the source site
- 128 -
you can rename it FridayRefresh on the target site.
target_scheduled_action_type
No* The type of schedule, eitherExtract, for extractrefreshes, orSubscription, forsubscription deliveries onthe target site.
*In rare cases, theremaybe questionmarks (???) inthis column. If there are,replace themwith eitherExtract or Subscription,matching the entry you seeunder source_scheduled_action_type.
mappingsSiteMapper source_url_namespac-e
No The site ID of the sourcesite.
target_url_namespac-e
No The site ID of the targetsite.
map-pingsSystemUserNameMapper
source_name
No The username of a user onthe source site.
source_domain_name
No The user authenticationtype on the source site:either local, for LocalAuthentication, a domainname (such asexample.com orexample.lan) for ActiveDirectory, or external (for aTableauOnline site).
target_name
Yes Usernames for users whowill be assigned to thetarget site upon import.
Confirm that all theusernames listed exist onthe target server systemand replace any questionmarks (???) with a validusername from the target
- 129 -
server.
You can't createusernames by adding rowsto the CSV file. Similarly,you can't removeusernames by deletingrows.
You can edit a username inthe target_name columnto be different from itssource username as longas it already exists on thetarget server system usingthat different name. Forexample, a user can have asource_name value [email protected] and atarget_name value [email protected] as long as the [email protected] exists on the targetserver.
You can't map a user onthe source site to more thanone username on the targetsite.
target_domain_name
Yes The user authenticationtype on the target site:either local, for LocalAuthentication, or a domainname (such as example.-com or example.lan) for Act-ive Directory.
4. If youmake edits, save your changes and preserve the CSV files' formatting. Leave themapping files in their current location.
Finish the Site Import
To finish the site import:
1. Open a command prompt as an administrator and navigate to the bin directory onTableau Server. For example:
C:\Program Files\Tableau\Tableau Server\8.2\bin
- 130 -
2. Type the following command:
tabadmin importsite_verified <site ID> --importjobdir <PATH>
where <site ID> is the site ID of the target site and <PATH> is the directory that's onelevel up from themappings directory you used inVerify the Site's Mappings on page126. For example:tabadmin importsite_verified esales --importjobdirC:\ProgramData\Tableau\TableauServer\data\tabsvc\temp\import_esales_20140409185810071
For examples of other options you can use with the importsite_verifiedcommand, see importsite_verified on page 351.
3. Open the new site that you just imported and confirm that everything came in asexpected.
Multi-Site NavigationHere are some tips on how to navigate from site to site and identify which site you're using.
Site Sign-In
If you are amember of multiple sites, when you sign in to the server, you are prompted tochoose a site:
Navigating to Other Sites
If you belong tomultiple sites, you'll see a Site menu at the top of the page:
- 131 -
To sign in to a different site, click the Site menu and select the site:
Identifying Your Site
If the server is runningmultiple sites yet you only belong to one site, you are not prompted tochoose your site at server sign-in . After you sign in, you do not see a Site menu at the top of thepage:
However, your web browser URLwill show a t followed by the site ID for your site:
If the server isn't runningmultiple sites, your web browser URLwill look similar to this (no t, nosite ID). If you see this, you are using Tableau's built-in site, which is namedDefault.
Server MaintenanceAs a system administrator, you will want to check the status of the server, analyze andmonitorthe activity on the server, manage scheduled tasks, or perform certain maintenance activitiessuch as rebuilding the search index. In addition, there are several settings that youmaywant tospecify to customize the user experience for people using the server. You can do all of thesetasks from theMaintenance page.
View Server Process StatusYou can use the Status table on theMaintenance page to view the state of Tableau processeson each Tableau server:
- 132 -
For information about unlicensed status for a VizQL Server process, seeHandle anUnlicensed VizQL Server Process on page 387.
To display amachine-readable version of the above information, from theMaintenance page,replace the word status in your URLwith systeminfo (for example,http://jsmith/admin/systeminfo). A web page similar to the following appears:
The types of status for a Tableau service are OK, Busy, Down, and Standby.
Access Status RemotelyAs the Tableau administrator, only you can see the tools on theMaintenance page, includingthe Status table. You can, however, make themachine-readable version of the Status tableavailable to non-admin users and to computers other than the one that's hosting TableauServer—for example, as part of a remotemonitoring process. To grant remote access toTableau Service status:
1. On the computer running the primary Tableau Server, open the Tableau Server configfile:ProgramData\Tableau\Tableau Server\config\tabsvc.yml
2. Add the line wgserver.systeminfo.allow_referrer_ips: <IP address>
- 133 -
to tabsvc. yml, where <IP address> is the IPv4 address of the computer you'd like toadd. If you are granting service status access tomultiple computers, use commas (nospaces) to separate each entry. For example:
3. Save and close tabsvc.yml.
4. Open a command prompt as an administrator and type:cd "C:\Program Files\Tableau\Tableau Server\8.2\bin"
5. Then use the following command to restart the Tableau Server processes:
tabadmin restart
Now, users at computers whose IP addresses or computer names have been added totabsvc.yml can view Tableau process status by entering the URLhttp://<server>/admin/systeminfo in a browser or from a command line (forexample, curl http://jsmith/admin/systeminfo). This functionality can alsobe used as part of an automated remotemonitoring process.
Rebuild the Search IndexIf for any reason the search index stops returning the correct results or ismissing results, youmay need to rebuild the search index. Additionally, you should rebuild the search index if theindexer goes down for an extended period of time.
- 134 -
1. To rebuild the search index, on the Admin tab, clickMaintenance:
2. ClickRebuild search index to begin.
Clear Saved Data Connection PasswordsAs the administrator, if you enable the Saved Passwords setting, server users can save datasource passwords acrossmultiple visits and browsers. You can reset all of the passwords forall Tableau Server users, which forces them to sign in to the data sources the next time theyvisit a view that requires database authentication. Server users can also clear their saved dataconnection passwords on an individual basis using their User Preferences page.
To clear saved data connection passwords for all server users:
- 135 -
1. Click theMaintenance link in the Administration section on the left side of the page:
2. Under Activities, clickClear all saved data connection passwords for all users.
Archive Logs on Maintenance Page (Snapshot)You can generate and download a snapshot (archive) of the Tableau Server log files from aweb browser, without opening a command prompt. This zipped snapshot contains a copy of upto seven days of log file data from Tableau Server and anyworker servers (if you have adistributed environment). The snapshot process does not change or remove either the TableauServer log files or the log archives created with tabadmin.
Note To specify the amount of data you want to collect or the name of the zip file you arecreating, use tabadmin to create an archive of server logs. For more information, seeArchive Logs on Command Line (tabadmin) on page 378.
To generate a snapshot of server log files:
- 136 -
1. On the Admin tab, clickMaintenance:
2. Under Activities, clickGenerate and download a snapshot of log files to open thesnapshot options:
3. ClickGenerate Snapshot to create a snapshot of the Tableau Server logs. TheGenerate Snapshot button is available only if there is no existing snapshot.
Log archives created with tabadmin do not affect the availability of this option.
4. ClickDownload Snapshot to download the log snapshot to your web browser's defaultdownload location. This option is available after you create a snapshot.
- 137 -
Google Chrome shows you the download in the bottom of the window:
5. Click the arrow and then clickOpen to unzip the snapshot or Show in folder to seewhere it was downloaded:
6. (Optional) ClickDelete Snapshot to delete a log snapshot. This option is available afteryou create a snapshot. You need to delete the existing snapshot before you can create anew one.
- 138 -
For example, youmight want to delete the snapshot that you created before an eventthat you want to investigate.
Maintenance SettingsThe following settings are available in the Settings section of theMaintenance page on theserver:
Setting DescriptionEmbeddedCredentials
Allows publishers to attach passwords to published workbooks that willautomatically authenticate web users to connect to data sources. Thepasswords are attached to workbooks and are only accessible on server. Thatis, when the workbook is opened in Tableau Desktop, users will still need toenter a user name and password to connect to the data source.When thissetting is turned off, all existing embedded passwords are saved but are notused for authentication. That way if you turn the setting back on, users don'thave to re-embed the passwords.
Scheduling Allows publishers to assign workbooks to schedules. This option is only avail-able if Embedded Credentials is enabled.When this setting is enabled, pub-lishers will see scheduling options in the Publish dialog box.
SavedPasswords
Allows users to save data source passwords acrossmultiple visits andbrowsers. By default users can choose to "Remember my password until I signout," which lets them save their password during a single browser session.When theSaved Passwords setting is selected a user can instead choose toRemember my password, which saves the password acrossmultiple visits andbrowsers so users will be automatically authenticated regardless of the com-puter they are using. You, as an administrator, can clear all saved passwordsat any time. In addition, users can clear their own saved passwords.
SaveAccessTokens
Allows users to store access tokenswith their user preferences. Access tokensare provided by cloud data sources that support OAuth connections, and theyare used instead of user names and passwords to grant access to the data. Formore information, seeProtect Credentials for Cloud Data on page 280.
EnableGuest
Allows users to view and interact with embedded viewswithout having to signin to a Tableau Server account. Permission can be assigned to the Guest Useraccount to control the interactivity allowed for each view. This option is onlyavailable if you have a core-based server license. This option can be used with
- 139 -
Enable automatic logon, an option you can select during Setup.Defaultstart page
Takes you to the server's current default start page for all users. SeeSet theDefault Start Page for All Users below for steps on how to change it. Indi-vidual users will be able to override this setting (seeYour User PreferencesPage on page 79 for details).
Default lan-guage andlocale
Controls the language used for the server user interface and the locale usedfor views. Individual users can override this setting on their User Preferencespage. Also, web browser settings are the first thing that’s used to determinewhich language and locale are used. See Language and Locale on page 154for more information.
Reset allsettings totheirdefault val-ues
Any server settings that have been changed since Setup are returned to theiroriginal state.
Set the Default Start Page for All Users
By default, Tableau Server installs with the Views page as the default start page for all users.As the administrator, you can change this to another page that all users have access to, suchas theWorkbooks page. Individual users will be able to override your setting (seeYour UserPreferences Page on page 79 for details).To set the default start page for all users:
1. Navigate to the page you want to be the default page.
2. Click your name on the upper right corner of the page.
3. SelectMake this the start page for all users.
Tableau Server MonitorTableau Server Monitor is installed as part of Tableau Server and can be accessed in theWindows system tray.
- 140 -
Using this tool you can start and stop the server, open Tableau Server, and display serverstatus.
Open the Server
This command launches Tableau Server in your web browser. This is an easyway to accessthe web application and the associatedmaintenance tools.
Start/Stop the Server
You can start and stop the server using these commands.When you stop the server youmakeit unavailable to all of your users and terminate any sessions that are currently in progress. Ifsomeone is publishing a workbookwhen the server is stopped, the process is abandoned. As aresult, only some of the worksheets in the workbookmay be published to the server. Becausestopping the server can be very disruptive to your users, be sure to warn them prior to thisoperation or planmaintenance during non-business hours.
Restart the Server
This command restarts the server. While the server is restarting it will be unavailable to allusers. Be sure to warn your users of the outage prior to this operation. You will need to restartthe server if youmake changes to the Tableau Server configuration.
Display Status
This command opens a screen tip containing the status of each process. For more detailedstatus, use theMaintenance page.
Manage Product Keys
This command opens the product keymanager where you can add and remove product keys.
Exit
This command closes Tableau Server Monitor. It does not stop Tableau Server. You can re-open the application by selectingAll Programs > Tableau Server 8.2 > Tableau Server
- 141 -
Monitor on theWindowsStart menu.
Data SourcesA Tableau Server data source is a reusable connection to data. It can include a data extract orinformation for a pass-through connection to a live, relational database. It can also include alayer of customizations, such as calculations, groups, or sets. (Cube data sources have specificlimitations. For more information, seeMultidimensional (Cube) Data Sources on page144.)
Tableau Server data sources are created in Tableau Desktop, then published to the server.For details on how to create, download, and edit Tableau Server data sources, see theTableau Desktop help.
Once a data source has been published, Tableau Server users with the appropriatepermissions can use it to create a workbook from scratch, on the server. SeeCreate aWorkbook and Build a View on page 167 for details.
Administrators can perform the following taskswith Tableau Server data sources:
l Edit and view data source permissions:Use permissions to specify which users orgroups can connect to data sources, modify them, and download them. See Settingpermissions for a data source for more information.
l Schedule data source extracts for refresh:If a data source includes an extract, youcan assign the extract to a refresh schedule. See Scheduling Tasks for moreinformation.
Although the above tasks can also be performed in Tableau Desktop by the person whopublishes the data source, it is general best practice for administrators tomanage these taskson the server. Administrators can also remove a data source or add tags to it.
Manage Data SourcesFor users to work with Tableau Server data sources, they need to have the appropriatepermissions for the data source. For data sources that are proxy connections, you should alsobe aware of how users will be authenticating to the database, and whether you have theappropriate drivers installed on Tableau Server. For more information, see the following.
Set Permissions for a Data Source on page 192Database Drivers on page 42Data Security on page 220
About Tableau Data ServerTableau’s data server is a server component that lets you centrallymanage and store TableauServer data sources. A data source is a reusable connection to data. The data can be locatedeither in Tableau’s data engine, as an extract, or in a live relational database. For relationaldatabase connections, the information stored in the data source is used for a pass-through
- 142 -
connection. The data source can also include customizations you’vemade at the field-level inTableau Desktop, such as calculations, dimension aliases, groups, or sets.
For administrators, there aremany advantages to using Tableau Server data sources.Because one data source extract can be used bymanyworkbooks, you save on server spaceand processing time. Extract refreshes can be scheduled per-extract instead of per-workbook,and when a workbook using a Tableau Server data source is downloaded, the data extractstays on the server, resulting in less network traffic. Finally, if a database driver is required for aconnection, you only have to install the driver once, on Tableau Server, instead of multipletimes, on all your users’ desktops.
To use the data server, all authors have to do is connect to data in Tableau Desktop, either bycreating an extract or a connection to a live relational database, and publish it to TableauServer. Once published, these reusable data sources and the server contain everythingworkbook authors need to quickly connect to data and start authoring. To change a publisheddata source, you download it to Tableau Desktop, make your changes, then republish,overwriting your original. Note that any new members you add to a parameter or any changesyoumake to the default sort order are not part of the data source (they are part of theworkbook).
If you are running a distributed installation of Tableau Server and expect data sources to beheavily used, there are several ways you can optimize your server deployment. SeeDistributed Environments on page 38 for more information.
Note: To use publishedmultidimensional (cube) data sources, youmust download themto Tableau Desktop, somany of the above advantages do not apply. For moreinformation, seeMultidimensional (Cube) Data Sources on page 144.
Use Data Sources
If you’re a workbook author, you can use a Tableau Server data source to create a newworkbook or edit an existing one. You can work with data sources from Tableau Desktop or theTableau Server web authoring environment.Work With Data Sources from Tableau Desktop
On the Connect to Data page in Tableau Desktop, clickTableau Server, then provide yourcredentials:
- 143 -
After you sign in to Tableau Server, data sources available to you are listed on the right.
Note: For considerations specific to cube data sources, seeMultidimensional (Cube)Data Sources on the next page.
To see a data source, the person who publishes it has to set the Connect permission toAllowfor you as a user. By default, all users have this permission.
Select a data source you want to use. The data source loads in the Data window in theworkbook. Tableau Server data sources have a Tableau icon instead of a database icon:
- 144 -
Work with a Data Source in theWeb Authoring Environment
After you sign in to Tableau Server, in the left navigation column, selectData Sources. If youare an administrator, this is on the Content tab.
In the list of data sources, select the check box next to the one you want to use, and then selectNewWorkbook.For more information, seeCreate a Workbook and Build a View on page 167.
For more information about publishing data sources from Tableau Desktop, see Publish DataSources in the Tableau Desktop help.
Multidimensional (Cube) Data SourcesMultidimensional (cube) data sources have certain characteristics that make them unique inTableau.
Cube data sources do not support pass-through connections. Thismeans that when a cubedata source is published, you cannot make a connection from Tableau Server using the datasource. It alsomeans you cannot create a workbook using the data source in Tableau Server.
Publishing a cube data source to Tableau Server gives you the ability to store the data sourceon the server. However, to use the data source, youmust download the data source toTableau Desktop and use it locally. To download a published data source you need:
l TheDownload/Web Save As permission for the data source. For more information,seeWork with Permissions on page 188 andSet Permissions for a Data Sourceon page 192.
l Correct drivers installed and ports opened on computer running Tableau Desktop.
Troubleshoot Data SourcesFor users to work with Tableau Server data sources, up to three things need to be in place:
- 145 -
l Permissions for the data source: Anyone connecting to a data sourcemust have theConnect andView permissions for it. This also applies to users accessing views thatconnect to data sources. Anyone publishing andmodifying data sourcesmust belicensed to Publish and also have theWrite/Save As andDownload/Web Save Aspermissions. SeeWork with Permissions on page 188 andSet Permissions for aData Source on page 192 for more information.Multidimensional (cube) data sources have to be downloaded and used in TableauDesktop, so they requireDownload/Web Save As permission. For more informationabout cubes in Tableau, seeMultidimensional (Cube) Data Sources on the previouspage.
l Ability to authenticate to the database: There are several ways you can connect todata in Tableau and control who has access to what. Basically, whichever entity isconnecting to the databasemust be able to authenticate. The entity could be TableauServer performing an extract refresh. It could be a Tableau Desktop user connecting to adata source that then connects to a live database. It could also be a Tableau Server userwho’s accessing a view that connects to a live database. Refer toData Security onpage 220 to learnmore about your options.
l Database drivers: If the person who created and published the data source in TableauDesktop needed to install additional database drivers, youmay need to install them onTableau Server aswell. If you are running a distributed installation of Tableau Serverwhere, for example, the data server process is running on a worker server, any requireddatabase driversmust be installed there aswell as on the primary server. Otherprocesses require drivers aswell. SeeDatabase Drivers on page 42 for moreinformation.
Data Source Error Messages
Here are some errors that workbook authors and other usersmay encounter as theywork withdata sources and views:
Permission to access this Tableau Server data source denied:Connecting to a datasource requires the Connect permission. SeeWork with Permissions on page 188 andSetPermissions for a Data Source on page 192 for more information.Data source not found: Someoneworking with a view may see this error if a data source isremoved from Tableau Server or if their Connect to Data page needs to be updated. To updatethe Connect to Data page in Tableau Desktop, click the Refresh icon:
- 146 -
Unable to connect to this Tableau Server data source: This error may appear if theconnection information for the data source has changed—for example, as a result of thedatabase server name changing. Look at the Data Connection information for the data sourceand confirm that it has the correct settings.
Unable to list Tableau Server data sources: This error may occur if a user is trying toaccess Tableau Server data sources and there are connectivity issues between TableauServer and Tableau Desktop.
Can’t connect with a cube data source: To use a publishedmultidimensional (cube) datasource, youmust download the data source and use it in Tableau Desktop. Verify that youhave the Download/Web Save As permission for the data source. For more informationabout cubes in Tableau, seeMultidimensional (Cube) Data Sources on page 144.
Data ConnectionsEvery workbook that is published to Tableau Server contains one or more connections. Theseconnections are listed under the Admin tab, on the Data Connections page:
- 147 -
The Difference Between Data Connections and Data SourcesData connections are different from data sources in that each connection is associated with asingle workbook and describes the attributes required for connecting to a data source (e.g.,server name, database name, etc.). That means if you have three workbooks that connect tothe same data source, you will still have three connections listed on the connections page.
Searching for Data ConnectionsThe Search area at the top of the Data Connections page helps you find connections bydatabase server name, username, port, general connection type, and bywhether or not thedatabase credentials are embedded. To use this area to search for a connection, fill in one ormore areas and click Search:
Which Connections Can I Edit?You can edit connection information for live database connections and for extracts that need tobe refreshed by Tableau Server. For example, youmay have a large number of workbooksthat connect to a database on a specific database server. If the name of the server changes,you can update all of the workbooks at once so they reference the new server name. Anotherexample is if a workbook connects to a database using a specific user name and password.You can quickly update all of the workbooks to use a different set of credentials.
For details on how to edit data connections, see the related topic link below.
Edit Data ConnectionsOn the Data Connections page, server administrators canmanage the connection informationfor published workbooks. Here you can change the connection type to store a different useraccount or type of authentication with a data source, or remove embedded passwords andrequire users to sign in each time.
For example, for some cloud data sources, instead of database credentials, youmight want theconnection to use a pre-configuredOAuth access token. For information about OAuthconnections, seeProtect Credentials for Cloud Data on page 280.
Note If you are not a server administrator, but you have edit permissions for a datasource, you can access the data connection settings on the Data Sources page.
- 148 -
1. Sign in to the site that has the data connections you want to modify, and clickDataConnections to display the Data Connections page.
2. Browse the list of connections or use the search filters at the top of the list to narrowdown the results.
You can search by the data server name and port, connection type, and the databaseuser name. You can also exclude or include data sourceswith embedded passwords.
The values you type into theServer andDatabase User Name fields are treatedas regular expressions.
3. Select the check boxes for the connections you want to modify, and then click theEditlink at the top of the list.
- 149 -
4. Type a new value for one or more of the connection attributes.
For connection options for Google and Salesforce.com data sources, seeAuthentication Options for Google and Salesforce.com below later in this topic.
If a database or database driver doesn’t support connecting by using an IP address, youmust enter the database name as the value for Server. All attributes selected in theChange? columnwill be updated when you clickSubmit. If you select the check box foran attribute and leave theNew Value field blank, the attribute will be empty.
5. ClickSubmit.6. Refresh the Data Connections page (press F5 or Ctrl+R) for your changes to take
effect.
Authentication Options for Google and Salesforce.com
Google BigQuery, Google Analytics, and Salesforce.com provide a protected authenticationoption. When you select this option, the connection is created through anOAuth access token.Database credentials do not need to be stored in Tableau, and all users connect through thisaccess token, including Tableau Desktop users who want to create or edit workbooks usingthis connection.
For an overview of the OAuth process, seeProtect Credentials for Cloud Data on page280.Google Authentication Options
When you edit Google BigQuery or Google Analytics connections, select either of the followingoptions in the Edit Data Connection dialog box:
l SelectAlways access…to authenticate through a designated account, and then selectan existing account from the list or select authenticate account now... to add a new
- 150 -
one.
When you add a new account, the Google sign-in page appears. After you provide yourdatabase credentials, Google prompts you to confirm Tableau access to the data. Whenyou clickAccept, Google returns an access token to use for connecting to the data.
If you create extracts of your Google data source, select this first option, so thatyou can schedule refresh tasks.
l SelectPrompt users to require users to connect through their own individual accesstokens or sign in each time they connect.
Salesforce.com Authentication Options
When you edit Salesforce.com connections, you can select any of the following options in theEdit Data Connection dialog box:
l SelectEnable scheduled extract refreshes using...to use a protectedOAuthconnection and schedule refresh tasks, and then select an existing account from the listor click authenticate account now on Salesforce to add a new one.
When you add a new account, the Salesforce.com sign-in page appears. After youprovide your database credentials, Salesforce.com prompts you to confirm Tableauaccess to the data.
- 151 -
When you allow Tableau access, Salesforce.com creates an access token throughwhich it connects to the data.
l SelectEmbed a username and password to use a traditional authenticationmethod.l SelectNo scheduled refreshes to require users to sign in to Salesforce.com each timethey connect.
Monitor Progress
When you save your changes in the Edit Data Connection dialog box, the dialog displays theprogress. If you close the dialog box, themodifications continue to run in the background untilcompleted. Tableau Server will make asmany changes as possible. Any failures will beskipped, but theywill not impede other changes. For example, if you try to change the servername and add a password to several connections, the server nameswill be changed, and thepasswords on workbookswill be changed. However, because you cannot add a password to adata source, the passwords for the data sourceswill not be changed.
For information about checking the progress of these tasks, seeBackground Tasks on page159.
Customize the ServerYou can customize how Tableau Server looks to personalize it for your company or group. Forexample, you can change the name that appears in screen tips andmessages, and you canchange the logo that appears onmost server pages.
- 152 -
You can also customize how users can interact with the server. For example, you can allowworkbook publishers to embed their data source credentials so that when people click apublished view with a connection to a live data source they get immediate access to the viewand don’t have to supply their database credentials first.
You can also control which language is used for the server user interface and which locale isused for views.
See the following topics for more information on customizing Tableau Server:
Change the Name or LogoYou can customize the following aspects of Tableau Server’s look and feel:
Change the Name
You can customize Tableau Server’s look and feel by customizing the name that appears intooltips andmessages. For example, if you change the name toMyCo, the text on the serverSign In page reads "Enter your MyCo username and password to log on, " and the tooltip forthe home navigation icon displaysMyCo Home instead of Tableau Server Home:
The copyright information at the bottom of every server page will still list Tableau (for example,©2013, Tableau Software, Incorporated and its licensors. All rights reserved.)
If you are using Active Directory for authentication, you cannot customize the company nameon the Sign In page.
To change the name that appears in tooltips andmessages:
1. Open a command prompt as an administrator and type the following:
cd "C:\Program Files\Tableau\Tableau Server\8.2\bin"
2. Change the name by typing the following:tabadmin customize name "new_name"
In the above line, replace "new_name" with the text that you want to appear as the nameon the server. Example: tabadmin customize name "Company Server"
3. Restart the server for the change to take effect by typing:tabadmin restart
Change the Logo
You can customize Tableau Server’s look and feel by customizing the large logo that appearson the Tableau Server logon page and in the left column of themain server pages (such as theProjects page,Workbooks page, Maintenance page, etc.). The supported large logo size is up
- 153 -
to 160 x 160 px and is implemented by running the tabadmin customize logocommand. You can also customize the small logo that appears in the upper left for everyworkbook and view. The supported small logo size is up to 32 x 32 px and is implemented byrunning the tabadmin customize smalllogo command.
If an image is larger than 160 x 160 px (large logo) or 32 x 32 px (small logo), it will appear to beclipped. The image file you use should be in GIF, JPEG, or PNG format.The Tableau logo thatappears on the server's web browser tab and to the left of the URL address cannot bechanged.
- 154 -
To change the logo:
1. Open a command prompt as an administrator and type the following:
cd "C:\Program Files\Tableau\Tableau Server\8.2\bin"
2. Change the logo by typing the following for a "large size" logo (up to 160 x 160 px, but notsmaller than 32 x 32 px):tabadmin customize logo "C:\My Pictures\logo.png"
If your logo is 32 x 32 px or smaller, use the following command:
tabadmin customize smalllogo "C:\My Pictures\logo.png"
3. Restart the server for the change to take effect by typing:tabadmin restart
Restore the Default Name or Logo
You can restore Tableau Server’s default look and feel by doing the following:
1. Open a command prompt as an administrator and type the following:
cd "C:\Program Files\Tableau\Tableau Server\8.2\bin"
2. Change the logo by typing the following:tabadmin customize <parameter> -d
In the above line, replace <parameter>with what you want to restore, either name orlogo.
3. Restart the server for the change to take effect by typing:tabadmin restart
Language and LocaleTableau Server is localized into several languages and has language and locale settings thatyou can configure on a per-user (seeYour User Preferences Page on page 79) and system-wide basis (seeMaintenance Settings on page 138). The Language setting controls userinterface (UI) items such asmenus andmessages. The Locale setting controls items in viewssuch as number formatting and currency.
Default Settings
Tableau Server obtains its default language setting during Setup. If the host computer is set toa language Tableau Server supports, it installs with that language. If it’s not a supportedlanguage, Tableau Server installs in English.
How Language and Locale are Determined
- 155 -
Another influence on which language and locale display when a user clicks a view is the user’sweb browser. If a server user has not specified a Language setting on their User Accountpage, and their web browser is set to a language that Tableau Server supports, the browser’slanguage will be used—even if Tableau Server itself is set to a different language.
Here’s an example: Assume that Tableau Server has a system-wide setting of English as theLanguage for all users. Server user Claude does not have a language specified on hisTableau Server User Account page. Claude’s browser usesGerman (Germany) for itslanguage/locale.
WhenClaude signs in to Tableau Server, the server UI displays in German and when he clicksView A, it’s using theGermany locale for numbers and currency. If Claude had set his useraccount Language and Locale to French (France), the UI and view would have beendisplayed in French. His user account setting supercedes those of his web browser, and bothof those have precedence over Tableau Server’s system-wide setting.
Another setting to be aware of is the Locale setting in Tableau Desktop (File >WorkbookLocale). This setting determines the locale of the data in the view, such aswhich currency islisted or how numbers are formatted. By default, Locale in Tableau Desktop is set toAutomatic. However, an author can override that by selecting a specific locale. Using theabove example, if the author of View A set Locale toGreek (Greece), certain aspects of thedata in View A would display using theGreek (Greece) locale.
Here are the settings Tableau uses to determine language and locale, in the following order ofprecedence:
1. Workbook locale (set in Tableau Desktop)
2. Tableau Server User Account language/locale settings
3. Web browser language/locale
4. Tableau Server Maintenance page language/locale settings
5. Host computer’s language/locale settings
Administrative ViewsTableau Server comeswith several views for administrators, to helpmonitor activity onTableau Server. Administrative views are located in the Analysis table on theMaintenancepage:
See the following for more information:
- 156 -
Server ActivityThe Server Activity administrative view gives you a snapshot of Tableau Server activity duringthe past 30 days.
In Total Views Over Time, you can hover your mouse over any point in the line and see atooltip that shows the number of views that were opened that day, along with other information:
Click at a point on the line to update the bar charts below to show which workbookswere beingviewed that day and whowas doing themost viewing:
Selecting amark in Total Views Over Time also filters the 24-Hour Total Viewing Patternto show the viewing pattern for a particular day. If nomarks are selected in Total Views Over
- 157 -
Time, 24-Hour Total Viewing Pattern sums the data in Total Views Over Time anddisplays it in a 24-hour time period so that you can see typical patterns over the course of a day:
User ActivityTheUser Activity view can help you gauge how heavily your Tableau Server installation isbeing used and whether youmay need to buy additional licenses. Specifically, this view showsyou who is signed into Tableau Server, fromwhere, and when they last interacted with theserver.
If a user is signed in frommultiple browsers, that will be shown aswell. For example, if a usersigns in once from Internet Explorer and once fromMozilla Firefox, that user's name appearstwice. But if a user signs in twice fromMozilla Firefox, the user's name appears just once.
Currently Active means that the user interacted with the server during the past fiveminutes.Recently Active indicates that the user was active five to fifteenminutes ago, and Idle meansthere's been no activity from the user for the last 15minutes. By default, after four hours of
- 158 -
inactivity, users are signed off of Tableau Server. You can change this setting by using thetabadmin tabadmin set options on page 358 option.In theDetailed User Activity view, circles indicate an action, such as signing in or filtering aview. Bars span the total time period over which there was activity. To learnmore, just hoverover an area and a tooltip appears:
Performance HistoryUse View Performance History to see which views are themost expensive in terms of serverperformance.
There are two different requests associated with views:
l Load View (initial load) requests, in orange
These include extraction of data from the repository and initial connection to the datasource.
l Compute View requests, in blue
- 159 -
These includemeta data checks, data gathering queries, local computing, and viewrendering for the initial load of a workbook. Subsequent filtering and drilling down do notimpact these.
Outlier marks represent requests with the biggest impact on server performance.
In the example below, the Load View request for the "by region" view in the "USSales01"workbook took 0.235 seconds to get information about the workbook andmake an initialconnection to the data source:
TheCompute View request for the same view took 5.398 seconds for data queries, localcomputing and view rendering for the initial display:
Background TasksThe Background Tasks view displays tasks that the server runs. Themost common tasks arethose associated with user actions. These are selected by default under Task Type:
- 160 -
Tasks can have a status of successful completion, error, in process, or pending:
Icon DescriptionError—Server was unable to complete the task.
Success—Server completed the task.In process—Server is currently completing the task.Pending—A task that the server has not yet started.
For details on a task, hover over its icon:
- 161 -
Tableau Server can runmultiple background processes in parallel. The IP addresses underBackground ID in the Background Tasks view show you whichmachines are assigned to runbackground processes:
A multi-coremachine runningmore than one background processwill be listed with <IPaddress>:0 for the first process, <IP address>:1 for the second, and so on.
Space UsageThe Space Usage view can help you identify which workbooks and data sources are taking upthemost disk space on the server. Disk space usage is displayed by user, project, and by thesize of the workbook or data source and is rounded down to the nearest number:
- 162 -
Move your cursor over any size bar to display usage details:
You can also drill into the links in the tooltip. For example, you can go to the user details for theuser, or see the workbook.
Customized ViewsPeople working with views can use the Remember my changes option to save theircustomized views and publishers can allow or prevent the sharing of customized views.
The Customized Views administrative view lists all the views on the server that have beencustomized withRemember my changes. It can be used as one indicator of a view'spopularity or importance:
- 163 -
Create Custom Administrative ViewsIn addition to the pre-built administrative views available on theMaintenance page on theServer, you can use Tableau Desktop to query and build your own analyses of server activity.To do this, you can connect to and query views in the Tableau Server repository using one oftwo built-in users: the "tableau" or "readonly" user.
l The tableau user—The tableau user has access to special views and a subset of tablesin repository database. These views and tables are provided so that administrators cancreate custom administrative views. Tableaumakes an effort to limit changes to thesetables and views so that custom views built with them do not break.
l The readonly user—The readonly user has access to a large number of the repositorytables, providingmore data about server usage. Administrators can use these to createcustom administrative views too, but many of the tables are intended primarily to supportthe functioning of Tableau Server andmay be changed or removed without warning.Thismeans that views created from these tables can breakwhen the database structureis changed.
Note: The readonly user is available in Tableau Server 8.2.5 and later.
For examples of using the readonly user to connect to the workgroup database, see thefollowing custom administrative view examples in the Tableau Knowledge Base: GroupMembership, Server Access, Server Access (2),andWorkgroup Usage.
Before you can connect using one of the built-in users, youmust enable access to the TableauServer database. After doing this you can use Tableau Desktop to connect to and query thedatabase as the tableau user or the readonly user.
- 164 -
Note: The tabadmin option auditing.enabled controls whether Tableau Server collectshistorical user activity and other information in the repository. It is enabled by default.The tabadmin option wgserver.audit_history_expiration_days controls how many daysof event history are kept in the repository. By default, this is set to 183 days. One thing tonote is that collecting historical events does impact the size of Tableau Server's backupfile (.tsbak).
Enabling External Access to the Tableau Server DatabaseYou can use Tableau Desktop to connect to and query the Tableau Server repository usingtwo special, built-in users. The "tableau" user has access to several database views you canuse as part of building your own analyses of Tableau Server activity. The "readonly" user hasaccess to additional database tables that you can use to create views for evenmore in-depthanalysis.
To access the Tableau Server repository, you need to use the tabadmin command line utility toenable external access to the database.
1. Open a command prompt as an administrator and type:
cd "C:\Program Files\Tableau\Tableau Server\8.2\bin"
2. Version 8.2.4 and earlier: Enter the following command to enable external access tothe database for the tableau user:
l tabadmin dbpass [password]
For example, to enable access for the "tableau" user with a password of"p@ssword":tabadmin dbpass p@ssword
Version 8.2.5 and later: Enter the following command to enable external access to thedatabase for the tableau user or the readonly user:
l tabadmin dbpass --username [tableau | readonly[password]
For example, to enable access for the "tableau" user with a password of"p@ssword":
tabadmin dbpass --username tableau p@ssword
or to enable access for the "readonly" user with a password of "p@ssword":tabadmin dbpass --username readonly p@ssword
Note: If no user is specified, dbpass enables access for the "tableau" user.
3. Restart Tableau Server:tabadmin restart
- 165 -
After you've enabled external access to the database, Tableau allows any IP address accessto the database as long as the correct password is provided. Follow the steps inConnectingto the Tableau Server Database below to connect.Disable external access to the Tableau Server Database
If you want to disable access by "tableau" or "readonly" after enabling it, use the tabadmindbpass again.
l Run the command tabadmin dbpass --disable --username [user] thenrestart the server.
For example:tabadmin dbpass --disable --username readonly
tabadmin restart
Note: If no user is specified, the --disable option disables access for the "tableau" user.
Connecting to the Tableau Server DatabaseAfter you enable external access to the Tableau Server database, follow the steps below toconnect to and query the database. The username you use will depend on which databaseviews and tables you want to use.
1. In Tableau Desktop selectData > Connect to Data, then selectPostgreSQL as thedatabase to connect to. Youmay need to install the PostgreSQL database drivers. Youcan download drivers fromwww.tableausoftware.com/drivers.
2. In the PostgreSQL connection dialog box, enter the name or URL for Tableau Server intheServer box. If you have a distributed server installation and a worker is hosting therepository, enter the name of the worker instead. If you are using an Apache loadbalancer, enter the actual name or ip address of the database server rather than theTableau Server name.
You should connect using the port you have set up for the pgsql.port (by default this is8060). For more information about ports, see TCP/IP Ports on page 313.
3. Enter workgroup as theDatabase to connect to.4. Connect using one of the following users and the password you specified:
Username: tableau or readonlyPassword: The password you specified when you enabled access to the TableauServer database for the specified user
5. ClickConnect.
- 166 -
6. Select one or more tables to connect to.
The "tableau" user has access to all of the tables the start with an underscore and hist_.For example, you can connect to _background_tasks and _datasources. The tablesthat begin with historical_ point to hist_ tables. The hist_ tables include informationabout server users that isn't currently presented in theUser Activity on page 157 view.The "readonly" user has access to a number of additional tables in the workgroupdatabase and can be used to query other information about server usage.
7. ClickGo to Worksheet.
Edit and Create ViewsUsers with the appropriate permissions for the web authoring environment can edit existingworkbooks or create new ones.
When you sign in to Tableau Server, the Views section appears by default. Views that youhave access to appear here as a result of either of the following processes:
- 167 -
l A Tableau Desktop user publishes the workbook containing the view to Tableau Server.l A user creates the view and saves the workbook directly in the Tableau Server web edit-ing environment.
Create a Workbook and Build a ViewYou can build a new view by creating a new sheet in an existing workbook or by creating a newworkbook. This topic shows how to build a view in a new workbook.
The following procedure uses theSuperstore sample data source that comeswith TableauDesktop, and is published to Tableau Server, to build a view that incorporates informationabout sales by category and region. If you have access to the Superstore sample data source,you can perform the steps in the procedure.
1. On theContent tab, selectData Sources.
2. In the data sources list, select the check box next to the data source you want tovisualize, and then selectNewWorkbook.
A new, blank view opens in the Tableau Server authoring environment.
- 168 -
Note: TheNewWorkbook option is not available if the data source is a for acube-based database. For more information seeMultidimensional (Cube)Data Sources on page 144.
3. From theMeasures pane, dragSales to the Columns shelf.
4. From the Dimensions pane, expandProduct to display its sub-categories, and thendragCategory to the Rows shelf.
- 169 -
Tableau now has enough to convert the data into a visualization (view), in this case ahorizontal bar chart.
5. From the Dimensions pane, dragRegion to the Rows shelf.The view now contains another layer of data—the categories are broken out by region.
Now suppose you want to view and compare sales by category in a single region. Youcan accomplish this using a filter.
6. From the Dimensions pane, dragRegion to the Filters shelf.
As you hover over the Filters shelf, a small triangle at the left of the field indicates thatyou can dropRegion onto the shelf.
- 170 -
A Filter control appears at the right edge of the page.
7. Clear the check boxes for all but one region that you want to analyze, and then selectthem all again.
8. You can enhance the visualization using color. DragRegion toColor on theMarkscard.
- 171 -
You now have a useful view that allows you to compare sales of different productcategories across regions:
Tip: To learn about selecting a different color palette for the bars or resizing them,seeMarks Card on page 181.
9. Instead of focusing on regional sales of each product, maybe you prefer a view that letsyoumore easily analyze a region’s overall product sales. On the Rows shelf, dragRegion to the left ofCategory.
The view refreshes to show sales of all products by region.
- 172 -
10. If you decide that you prefer the previous version of the view, you can clickUndo in theToolbar.
11. If you want to create a second worksheet, select theNewWorksheet tab at the bottomof the view.
Select the worksheet tab and selectRename Worksheet to give it a more descriptivename.
12. ClickSave to save the workbook. In theSave Workbook dialog box, complete the
- 173 -
following steps:l Specify the workbook name, and leaveProject set toDefault.l SelectShow sheets as tabs if you createdmultiple sheets and want their tabs toappear at the bottom of the view.
l SelectEmbed password for data source if you want users who do not have anaccount on the database to be able to see the view.
l When you are finished, clickSave.
Edit a ViewIn the Views section, you can open a view for editing either of the following ways:
l ClickEdit in the tooltip that appears when you hover the pointer over a thumbnail view.l Select a view to display it, and then clickEdit at the top of the view.
If the workbook publisher did not embed database credentials, you are prompted toprovide them.
- 174 -
Saving or Discarding Changes
While you are editing a view, you can save or discard changes at any time, using the linksabove the view area.
When you save your work, even though you entered the authoring environment from a singleview, the complete workbook is saved, including other views youmay or may not have edited.
l Save overwrites the original workbook.l Save As creates a new workbook in the same project.
If you want to keep both the original version of a view and your edited version, useSaveAs to create a new workbook.
If you selectShow sheets as tabs, the workbook permissions override the permissionson individual viewswithin the workbook, until the workbook is saved again without tabs.
l Revert discards edits and returns to the last saved version of the workbook.l Done exits the authoring environment.If you have unsaved changes, you are prompted to save them. If you do not savechanges, the unsaved changes are still present when you return to the authoringmodefor that view, for as long as you remain signed in to the current server session.
How you can save workbooks depends on the permissions granted by your administrator. Formore information, seeGrant Edit and Save Permissions on page 210.
The Tableau Server Authoring EnvironmentTheweb authoring environment is similar to Tableau Desktop. The Data window appears onthe left side, showing the names of the data sources included in the workbook, and the fields,parameters, and sets included in the active data source.
- 175 -
Likewise, in themain area, a toolbar appears across the top,Marks card andPages andFilters shelves to the left of the view, andColumns andRows shelves above the view. Anysheet tabs included in the workbook appear at the bottom of the view.
- 176 -
When you open a view for editing, you can edit the other views in the sameworkbook, but notdashboards or stories. You can also select theNew Sheet tab to begin creating a new view.
Toolbar
When you are editing a view, you can use the toolbar at the top of the view to perform commonactions.
Undo/Redo
Undo and redo an action or series of actions. You can undo or redo almost any type of changein the view by selecting these toolbar buttons.Pause Updates
When you place a field on a shelf, Tableau generates the view by querying the data source. Ifupdates seem slow when editing the view, you can pause updateswhile making a series ofedits, then turn them on again.Swap
Thismoves the fields on the Rows shelf to the Columns shelf and vice-versa. Most used withview types that are based on x- and y-axes.
- 177 -
Totals
You can automatically compute grand totals and subtotals for the data in a view. Select Totalsto see four options:
l Show Column Grand TotalsAdds a row showing totals for all columns in the view.l Show Row Grand TotalsAdds a column showing totals for all rows in the view.l Add All Subtotals Inserts subtotal rows and columns in the view, if you havemultipledimensions in a column or row.
l Remove All SubtotalsRemoves subtotal rows or columns.
Show/Hide Labels
Select to show or hidemarks labels in the view.View Size
Use the options under View Size to change the proportions of your view within the browserwindow, and go back and forth between seeing details and seeing the whole picture. The CellSize commands have different effects depending on the type of visualization.Worksheet
Contains options for making changes at the worksheet level. Create worksheets, modify sheetnames, clear sheet formatting, or clear the entire sheet.Export
Use the options under Export to capture parts of your view for use in other applications.
l Image: Displays the view, dashboard, or story as an image in a new browser tab.l Data: Displays the data from the view in a new browser window with two tabs:Sum-mary, showing aggregated data for the fields shown in the view, andUnderlying, show-ing underlying data for the selectedmarks in the visualization. If the new window doesnot open, youmay need to disable your browser's popup blocker.
l Crosstab: Saves the underlying data for the selectedmarks in the visualization to aCSV (comma-separated values) file which can then be opened inMicrosoft Excel.
l PDF: Opens the current view as a PDF in a new browser window. From there you cansave it to a file. If the new window does not open, youmay need to disable yourbrowser's popup blocker.
Show Me
Opens a control that shows a range of visualization types that you can use in Tableau.Whenyou display the Show Me list, Tableau uses the data in the current view to determine whichvisualization types tomake available for you to select. Among the available types, it draws adifferent color outline around the one that it determines is the best match for your data.
You can also hover over a visualization type to see what field types are required tomake thatvisualization type available.
Data Window
At the top of the Data window is a list of available data sources for the workbook. If you areediting an existing workbook, theremay bemultiple data sources. Select a data source to see
- 178 -
the dimensions andmeasures for that data source. If you are creating a new workbook, yousee just the data source fromwhich you created the workbook.
All data sources contain fields. These fields appear below the list of data sources in the Datawindow. Dimensions andmeasures always appear, other field types appear if they are presentin the data source:
l Dimensions are fields that contain discrete qualitative data. Examples of dimensionsinclude dates, customer names, and customer segments.
l Measures are fields that contain numerical data that can be aggregated. Examples ofmeasures include sales, profit, number of employees, temperature, frequency, andpressure.
l Sets are custom fields that define a subset of data based on some conditions. A set maybe based on a computed condition, which updates as the data changes, or a constant listof values. Setsmay be present in workbooks that you edit, but you cannot create sets.
l Parameters are dynamic values that can replace constant values in calculations, filters,and reference lines. Parametersmay be present in workbooks that you edit, but youcannot create parameters.
To build visualizations, you drag fields from the Data window to the Rows and Columnsshelves, theMarks card, or one of the other available shelves. For a demonstration, seeCreate a Workbook and Build a View on page 167.
Columns and Rows Shelves
Drag fields to the Columns shelf to create the columns of a table, or to the Rows shelf to createthe rows of a table. You can dragmultiple fields to either shelf.
Discrete values (typically, dimensions) are displayed in blue on the Columns and Row shelves;continuous values (typically, measures) are displayed in green.
At the right end of any field you place on the Columns or Rows shelf is a drop downmenu thatyou can use to configure the dimension or measure:
- 179 -
The options that are available depend on the type of field. The complete list of options includes:
l Include in TooltipBy default, all fields on the Columns and Rows shelf are included in the tooltips thatappear when youmove your mouse over one or moremarks in the view. Un-check thisoption to remove a field from tooltips.
l Show FilterChoose this option to add a filter for this field to the view. Users will then be able tospecify which data to include and exclude for this dimension or measure.
l Discrete/ContinuousUse these options to convert a continuous range of values into a set of discrete values,or a discrete set into a continuous range.
l Dimension/Attribute/MeasureUse this range of options to convert a dimension to ameasure or ameasure to adimension.
You can also define the option as an Attribute, which returns the value of the givenexpression if it only has a single value for all rows in the group, and otherwise displays anasterisk (*) character. Null values are ignored.
l Quick Table CalculationProvides a set of options for redefining themeaning of themarks for the value.
l RemoveRemoves the value from the Columns or Rows shelf.
- 180 -
Options for Date Dimension
An additional set of options is available for date dimensions:
Choose one of the options from the upper group to define the granularity of the data as discretevalues. For example, if you chooseMonth your view will combine the data for each namedmonth in your data across the full range of years:
There are exactly twelvemarks in the data--one for eachmonth. The November markcombines the data fromNovember 2008, November 2009, etc.
- 181 -
Choose one of the options from the lower group to define the granularity of the data ascontinuous values. For example, if you chooseMonth your view will show your datasequentially, over the range of availablemonths.
In this case there are 48marks in the data--one for eachmonth since November 2008.
Marks Card
When you drag fields to the view, the data are displayed usingmarks. Eachmark representsthe intersection of all of the dimensions in the view. For example, in a view with Region andYear dimensions, there is amark for every combination of those two field (East 2011, East2012,West 2011,West 2012, etc.).
Marks can be displayed inmany different ways including lines, shapes, bars, maps, and so on.You can show additional information about the data usingmark properties such as color, size,shape, labels, etc. The type of mark you use and themark properties are controlled by theMarks card. Drag fields to theMarks card to show more data. For example, the same viewabove is shown again below but this time withProfit on Color. With this additional information,it is clear that the Southern region was not profitable in 2010.
- 182 -
Control themarks in the view using theMarks card. Use the drop-downmenu to specify thetype of mark to show. Drag fields to theMarks card and use the drop-down controls to addmore information to the view and control the color, shape, size, labels, and number of marks inthe view.Mark Types
Mark types are available from theMarks card drop-downmenu.
Mark Properties
You can control the colors, size, shape, and other properties of themarks in the view. Drag afield to a property on theMarks card to encode themarks using your data.
- 183 -
The properties available vary amongmark types. For example, the Shape property is availableonly for the Shapemark type, and the Angle property is available only for the Piemark type.
The properties are:
Property DescriptionColor Encodes data by assigning different colors to themarks in a data view
based on the values of a field.
Quantitative color palettes are applied to continuous fields, such as aprofit measure.Categorical palettes are applied to discrete fields,such as a field representing geographic regions.
Change the color palette or transparency by selecting Color, and thenusing the palette control and slider.
Size Separatesmarks according to themembers in a dimension, andassigns a unique size to eachmember. Because size has an inherentorder (small to big), categorical sizeswork best for ordered data likeyears or quarters.
- 184 -
To change the overall size of marks in the view, select Size, and dragthe slider.
Label/Text Encodes data by assigning text labels to themarks. Whenworkingwith a text table, this property is called Text, and it shows the numbersassociated with a data view.
To display or hide the labels onmarks, select Label, and then selector clear the check box.
Detail When you place a dimension on the Rows or Columns shelf, thecategorical members create table headers. The headers representlevels of detail because they separate the data source rows intospecific categories. You can identify each category by themembername.
The Detail property also allows you to separate themarks in a dataview according to themembers (levels of detail) of a dimension.However, unlike the Rows and Columns shelf, this property does notmodify the table structure.
Tooltip Adds the field name and value to the tooltip for eachmark.Path Allows you to encode data by connectingmarks using a particular
drawing order. You can path-encode your data using either adimension or ameasure.When you place a dimension on Path,Tableau connects themarks according to themembers in thedimension. If the dimension is a date, the drawing order is given bythe date order. If the dimension holds words such as customer namesor product types, the drawing order is given by the order of themembers in the data source.When you place ameasure on Path,Tableau connects themarks according to the values of themeasure.
- 185 -
The Path property is available only when you select the line orpolygonmark type from theMarkmenu.
Shape Separates themarks according to themembers in the dimension, andassigns a unique shape to eachmember.
Filters Shelf
Use the Filters shelf to specify which data to include and exclude for a dimension or measure.For example, youmight want to analyze the profit for each customer segment, but only forcertain shipping containers and delivery times. By placing the Container dimension on theFilters shelf you can specify which containers to include. Similarly, you can put the DeliveryDate field on the Filters shelf to define which delivery times to include.
When you drag a dimension or measure to the Filters shelf, Tableau automatically inserts afilter control into the view for selecting the values to display. For example:
For dimensions, the filter control shows discrete values, as above. For measures, the controlshows a continuous range:
Hover your mouse to the right of the title for the filter control to specify how values in the controlare to be displayed:
- 186 -
Pages Shelf
Drag a dimension or measure to the Pages Shelf to break a view into a series of pages so youcan better analyze how a specific field affects the rest of the data in a view. Dragging adimension to the Pages shelf is like adding a new row for eachmember in the dimension.Dragging ameasure to the Pages shelf automatically converts themeasure into a discretemeasure that can be broken into individual pages.
When you drag a dimension or measure to the Pages shelf, Tableau automatically inserts acontrol into the view to let you navigate the pages in your view. For example:
You canmanually advance through the sequence of pages in any of the following ways:
l Use the drop-downmenu to select a value.l Use the forward and back buttons on either side of the drop-down list to navigatethrough the pages one at a time.
l Use the Page slider to quickly scroll forward and backward in the sequence of pages.
SelectShow History to show marks from previous pages in addition tomarks for the currentpage.
Tooltips
Place your cursor over amark in the view to see the tooltip for that mark.
Tooltips provide information on the values of dimensions andmeasures for the selectedmark:
Tooltips also provide these options:
l Keep OnlyExclude all marks from the view except this one.
l ExcludeExclude thismark only.
l Group MembersChoose the paperclip icon to create a new group, which is a dimension, from theselectedmark. Typically, you would select multiple marks and then create a group. For
- 187 -
example, if you have a dimension Region with valuesNorth, South, East andWest, youcould select South andWest and then create a group from them.
l View DataChoose the table icon to open a new browser window to display two tabs:Summary,which shows only data for the current mark, andUnderlying, which shows data for theentire view.
- 188 -
Work with PermissionsWhat you can do with views, workbooks, projects, and data sources on Tableau Server iscontrolled by both your license level (specified by an administrator) and the permissions set bythe author of the view or data source.
You can change permissions for an item if you have an Interactor license level and at least oneof the following is true:
l You are the owner of the workbook or data source (you published it to the server).
l You have been assigned the Set Permissions permission.
l You have been assigned the Project Leader permission for the project that contains theitem.
l You have been granted the Admin right.
See the following topics for more information:
How Permissions are DeterminedThe diagram below illustrates how permissions are evaluated.
- 189 -
If a workbook is configured to show sheets as tabs, all views inherit the workbookpermissions even if different permissions are specified on an individual view.
Set Permissions for Workbooks and ViewsFollow the steps below to set permissions for a workbook or a view.
1. From a page that displays one or more workbooks, or one or more views, click to selectone or more workbooks or views, then clickPermissions:
- 190 -
2. ClickAdd/Edit Permissions in the Permissions:Workbook or Permissions: Viewpage:
TheAssign Permissions to Contents option is shown for workbooks but notfor views.
3. In the Add/Edit Permissionswindow, select a user or group from the listing on the left:
- 191 -
You can configure the list to show users, groups, or both.
4. Select a predefined role from theRole drop-downmenu, or specify individualpermissions in the area below. The list of permissions and the predefined roles vary a bitdepending on whether you are setting permissions for a workbook or a view. SeePermissions Reference on page 197 for a table that defines the various permissionsand what items they apply to.
The available roles for workbooks and views are:
Role Appliesto...
Description
Viewer workbooks
views
Allows the user or group to view the workbook orview on the server.
Interactor workbooks
views
Allows the user or group to view the workbook orview on the server, edit workbook views, applyfilters, view underlying data, export images, andexport data. All other permissions are inheritedfrom the user's or group's project permissions.
Editor workbooks
views
Allows all permissions to the user or group
Data Source Con-nector
views Allows the user or group to connect to the datasource on the server. This permission is relevantfor viewswhen accessing a view that connects to adata source.
- 192 -
Data Source Editor views Allows the user or group to connect to data sourceson the server. Also to publish, edit, download,delete, and set permissions for a data source, andschedule refreshes for data sources you publish.This permission is relevant for viewswhen access-ing a view that connects to a data source.
5. You can configure permissions for one user or group, or for multiple users and groups.When you are finished, clickSubmit.
6. For workbooks, clickAssign Permissions to Contents to assign the permissions yousubmitted to the workbook and the contents of the workbook. This overwrites anyprevious permissions assigned to the worksheets. If you do not do this, the worksheetswill not have the permissions you submitted to the workbook.
Set Permissions for a Data SourceFollow the steps below to set permissions for a data source.
1. From the Data Sources page, click to select one or more data sources, then clickPermissions.
- 193 -
2. ClickAdd/Edit Permissions in the Permissions: Data Source page:
3. In the Add/Edit Permissionswindow, select a user or group from the listing on the left:
4. Select a predefined role from theRole drop-downmenu, or specify individualpermissions in the area below. SeePermissions Reference on page 197 for a tablethat defines the various permissions and what items they apply to.
The available roles for data sources are:
- 194 -
Role DescriptionData Source Con-nector
Allows the user or group to connect to the data source on theserver.
Data Source Editor Allows the user or group to connect to data sources on theserver. Also to publish, edit, download, delete, and set per-missions for a data source, and schedule refreshes for datasources you publish.
Note:Cube data sources, like those for Microsoft Analysis Services or OracleEssbase connections, must be used locally. To download the published datasource to Tableau Desktop, you need theDownload/Web Save As permissions.Youmust explicitly grant theDownload/Web Save Aspermissions because theData Source Connector role does not provide these. For more information, seeMultidimensional (Cube) Data Sources on page 144.
5. You can configure permissions for one user or group, or for multiple users and groups.When you are finished, clickSubmit.
Set Permissions for a ProjectAdministrators and Project Leaders can specify project permissions.When you create a newproject, it has the same permissions as theDefault project. You can set permissions for theproject to allow or deny individual users and groups permission to access the project. Tospecify project permissions:
1. ClickAdmin > Projects.2. Click to select one or more projects, then clickPermissions:
3. ClickAdd/Edit Permissions in the Permissions: Project page:
- 195 -
4. In the Add/Edit Permissionswindow, select a user or group from the listing on the left:
You can configure the list to show users, groups, or both.
5. Select a predefined role from theRole drop-downmenu, or specify individualpermissions in the area below. SeePermissions Reference on page 197 for a tablethat defines the various permissions and what items they apply to.
- 196 -
The available roles for projects are:
Role DescriptionViewer Allows the user or group to view the workbooks and views in
the project.Interactor Allows the user or group to view the workbooks and views in
the project, edit workbook views, apply filters, view underlyingdata, export images, and export data.
Editor Allows all permissions to the user or groupData Source Con-nector
Allows the user or group to connect to data sources in the pro-ject.
Data Source Editor Allows the user or group to connect to data sources in the pro-ject. Also to publish, edit, download, delete, and set per-missions for a data source, and schedule refreshes for datasources you publish. This permission is relevant for viewswhen accessing a view that connects to a data source.
Project Leader Allows the user or group to set permissions for all items in a pro-ject.
Publisher Allows the user or group all permissions needed for publishingworkbooks to the server.
The permissions you specify apply to the project itself. Any explicit permissions that are set onthe workbooks, views, and data sources in the project are not affected. You have, however, theoption to assign the project permissions to all of the workbooks, views, and data sources in theproject. In that case, those permissions override the existing permissions on the workbooksand views. For example, say there are several workbooks that have each been published withcustom permissions and you group the workbooks into a new project with a new permissionset. You can apply the new permissions to each of the workbooks by clickingAssignPermissions to Contents on the Permission page.
Check User PermissionsAt any time, you can see a user's permissions for a particular view, workbook, project, or datasource. From any page where you can set permissions, select a user from theCheck userpermissions drop-down list.
- 197 -
The permissions shown are specific to the view, workbook, data source, or project you haveselected.
Permissions ReferenceAdministrators and other authorized users can allow or deny permissions on actions that userscan perform in Tableau Server. Permissions can also be set in Tableau Desktop whenpublishing a workbook or data source to Tableau Server.
Administrators always have full control of all assets on Tableau Server, and site administratorshave full control of all assets on a site. If you publish a workbook or data source to TableauServer, you are the owner of that asset, and you retain full control over that asset.
The following table showswhich permissions apply to which items in Tableau Server, anddescribes the actions users can performwith each permission.
Permission Affects... When allowed, users can...View workbooks
data sources
views
projects
View the item on Tableau Server. A user who accesses aview that connects to a data sourcemust have both Viewpermission for the workbook and Connect permission forthe data source.
Note: If a workbook is configured to show sheets as tabs,all views inherit the workbook permissions even ifdifferent permissions are specified on an individual view.
Web Edit workbooks
views
Edit views in workbooks. SeeGrant Edit and SavePermissions on page 210.
- 198 -
Permission Affects... When allowed, users can...projects Permissions for worksheets (views) in a workbook are
copied (overwritten) from the workbook's permissionswhen you publish a workbook from Tableau Desktop.They are also copied when you clickAssignPermissions to Contents on thePermissions: Workbook page. If you selectShow sheetsas tabs when saving a workbook, the permissions for allworksheets (views) in the workbook are overwritten bythe permissions for the workbook, but only until such timeas tabs are disabled.
Special Consideration for theAll Users group: In theinterest of protecting a owner’s content from beingoverwritten by another user (either via publishing fromTableau Desktop or saving a web-edited workbook onTableau Server), whenever a user publishes into aproject where theAll Users group has permissions, theWrite/Web Save As permission for theAll Users groupis changed fromAllow to Inherit by default. You canmanuallymodify this permission by following the steps inSet Permissions for Workbooks and Views on page189 to change this from Inherit to Allow.
Write/WebSave
workbooks
data sources
views
projects
Overwrite the item on the server. When allowed, the usercan re-publish a workbook or data source from TableauDesktop, thereby becoming the owner and gaining allpermissions. Subsequently, the original owner's accessto the workbook is determined by that user's grouppermissions--and any further permissions the new ownerdecides to set.
This permission also determines the user's or group'sability to overwrite a workbook after editing it on theserver. SeeGrant Edit and Save Permissions onpage 210.
Download/WebSave As
workbooks
data sources
projects
When allowed, a user can download the item from theserver, and also save an edited workbook as a newworkbook on the server. SeeDownload Workbooks onpage 203 andGrant Edit and Save Permissions onpage 210.
Delete workbooks
data sources
views
projects
Delete the item.
- 199 -
Permission Affects... When allowed, users can...Filter workbooks
views
projects
Modify quick filters, keep only filters, and exclude data.SeeComment on Views on page 202.
Add Comment workbooks
views
projects
Add comments to views in a workbook.
ViewComments
workbooks
views
projects
View the comments associated with the views in aworkbook.
View SummaryData
workbooks
views
projects
View the aggregated data in a view, or in the user’sselection within the view, and download that data as atext file.
ViewUnderlyingData
workbooks
views
projects
View the raw data behind each row in a view, asrestricted by anymarks the user has selected, anddownload the data as a text file.
Export Image workbooks
views
projects
Export each view as an image.SeeExport Views on thenext page.
ShareCustomized
workbooks
views
projects
Make saved customizations to a view available for othersto see. Users can create custom views using theRemember my changes option in Tableau Server. SeeCustomized Views on page 162.
Move workbooks
views
projects
Move workbooks between projects.
SetPermissions
workbooks
data sources
views
projects
Specify permissions for the item. For workbooks, thispermission extends to the views in a workbook.
Connect data sources
views
projects
Connect to the data source. A user who accesses a viewthat connects to a data sourcemust have both Viewpermissions for the view and Connect permission for thedata source.
Project Leader projects Set permissions for all items in a project and for theproject itself.
- 200 -
Export ViewsYou can export the view as an Image or PDF. Alternatively, you can export the data as aCrosstab or a comma separated value file (Data). Select an option on theExportmenu onthe toolbar at the top of the view.
If you are exporting a dashboard to a PDF and the dashboard includes a web pageobject, the web page object is not included. Also, when you select an export option, theimage, PDF or data file must be generated. A message openswhen it is donegenerating so you can continue downloading the file.
To export a view as a PDF:
1. Open a view and from the Export toolbar button, selectPDF:
2. Select either aPortrait or Landscape orientation and aPaper Size:
- 201 -
3. Choose whether to print the entire workbook, the selection dashboard or story, or onlycertain sheets. Clicking the highlighted thumbnail for a sheet excludes it from the export:
4. ClickOK, then, in the Export PDF dialog box, clickDownload. Your PDF displays,ready to be printed:
- 202 -
Comment on ViewsYou can add comments to any view you have access to on Tableau Server. You can also seeany comments associated with a particular view.
Type your text in theComment text box located below the view and clickAdd.
You can add formatting to your comment by inserting hyperlinks, bolding, italics, andunderlining. Examples of how to add each of these types of formatting are shown in the tablebelow.
- 203 -
Format What to Type ExampleHyperlink “My Link”:http://www.tableausoftware.com My LinkBold *Bold Text* Bold TextItalics _Italic Text_ Italic TextUnderline +Underlined Text+ Underlined Text
Download WorkbooksWorkbooks can be downloaded using theDownload link in the upper right corner of the view.The downloaded workbook can be opened with a version of Tableau Desktop. Downloadingthe workbook from the server is the same as selectingServer > Open Workbook in thedesktop application. The workbook can only be opened if it is still published to the server.
This option is only available if you've been given theDownload/Web Save As permission bythe author of the workbook or an administrator. SeeWork with Permissions on page 188 tolearnmore.
Refresh DataIf the data source is changed, such as new fields have been added or data values and fieldnames have beenmodified, the view will reflect those changes the next time you load the page.However, youmay need tomanually update the view using theRefresh Data button on thetoolbar.
- 204 -
When you refresh the data, you clear any cache that may exist and retrieve the latest data fromthe data source. This option is different than thePause Automatic Updates below option,which still may load the view based on cached data. Depending on the size of your data sourceand the view, refreshing the datamay take longer than other queries that operate on cacheddata.
Pause Automatic UpdatesAs you interact with the view on the server, it will sometimes have to send a query to the datasource to update the data in the view. If you are working with a dense view with a lot of data ora very large data source, the automatic updatemay take a long time. To avoid waiting for eachupdate while youmake several changes you can clickPause Automatic Updates on thetoolbar.
When youResume Automatic Updates using the same toolbar button you only have to waitfor a single query to the data source.
Save PasswordsSometimes a view requires you to enter a database user name and password. If you haveaccess to the database you should enter your Username and password into the appropriatetext boxes. If you select theRemember my password option you will be automatically signedin each time you look at the view. Your sign in information is stored encrypted on the server soyou will be automatically signed in even between browser sessions and when accessing theview frommultiple computers. This is convenient when you have a select number of views thatyou access all the time.Note:Administrators can restrict whether to allow users to remember database passwords. If youare an administrator, seeMaintenance Settings on page 138 to learnmore.
- 205 -
Clearing and Resetting Saved Passwords
If your passwords are being saved (Saved Passwords is enabled on theMaintenance page),you can clear your saved passwords.When you do this, the next time you visit the server, youare prompted to enter your username and password. Youmaywant to do this if your usernameand password change so you can begin using and saving your new credentials.
1. Open your User Preferences page from the upper right drop-downmenu:
2. Under Saved Data Connection Passwords, clickClear All.
Administrators can also clear all saved passwords on the server using theClear allsaved passwords for all users link on theMaintenance page.
Save Your Custom ViewAs you filter, sort, and interact with a view, a gray dot appears next to theRemember mychangesmenu or the name of the view. The dot indicates that changes have beenmade. Usethismenu to save your changes as a custom view.
- 206 -
Any custom views that you or others create will always be related to the original view. As theoriginal view is updated or republished, customized versions of the view are also updated. If theoriginal view is deleted from the server, its related custom views are also deleted. If filters areremoved from the original view and it’s republished, the filters will be unavailable in customizedversions of the view. If filters are restored and the view is republished, customized versions ofthe view are restored.
Here aremore details on how to save a custom view:
1. Open the individual view that you want to customize.
2. Filter the data, change sort orders, highlight, zoom in or out, etc.
3.
Click theRemember my changes link or the name of the custom view. Then type aname for your custom view and clickRemember.
Tomake your custom view the one you see by default when you first open the view, selectChange default to <custom view name>. The word (Default) displays to the right of thecustom view’s name, indicating that this version of the view is your default.
- 207 -
Share ViewsEvery published view and workbook can be shared via email or embedded into anotherwebpage, wiki, or web application. Anyone viewing a shared view must have an account onTableau Server and permission to access the view.
Email a View
1. Click theShare link in the upper left corner of the view.2. Copy and paste the provided link into your email message.
- 208 -
Embed Views
You can share a view by embedding it into another webpage such as your wiki, blog, or webapplication.
1. Click theShare link in the upper left corner of the view.2. Copy the provided HTML code, and then paste it into the source code of the page in
which you want to embed the view.
- 209 -
Note: The embed code generated by Tableau will automatically refer to the currentview. For information about how embedded custom views are displayed in Tableau, seeEmbedCode for CustomViews.
Adjust an Embedded View’s Appearance
You can change how an embedded view looks by adjusting theDisplay Options. There youcan specify a fixed width, height, and whether to show the toolbar or tabs.
- 210 -
Grant Edit and Save PermissionsThis topic shows how administrators can set permissions for commonworkbook tasks,including the following:
l Editing existing workbooks.l Saving changes to existing workbooks, overwriting previous versions.l Saving changes to a new workbook, allowing creating new workbooks but not allowingoverwriting existing ones.
It also describes how to prevent inadvertently overwriting explicit permissions from a differentarea in the permissions structure.
Set User License and Publishing LevelsAdministrators assign a license level and user rights when they create or modify users. Toallow users to edit workbooks, you first provision the users as follows:
l The user must have the Interactor license level.l The user must be granted thePublish user right.
For more information, seeUsers on page 65 and Licenses and User Rights on page 82.
Allow Editing and Saving WorkbooksAfter you set up users or groups, set license levels, and grant publishing rights, you need to setpermissions at the project andworkbook levels, depending on the type of editing you want toallow. The primary permissions for editing and saving views include the following:
- 211 -
l Web Edit determineswhether the user can edit workbook views through webauthoring.
l Download/Web Save As determineswhether the user sees theSave andSave Ascommandswhile they are editing a view, and whether they can save their changes to anew workbook. Also determineswhether users can open a workbook on the serverusing Tableau Desktop.
l Write/Web Save determineswhether users can save changes to an existing workbookon the server (overwrite a workbook).
To allow a user or group to save changes to existing workbooks or to new workbooks, setthese three task-level permissions according to the tables in the following sections.
Allow users to save changes to existing and new workbooks
Permission For theproject
For appropriate work-books in the project
Web Edit Allow AllowDownload/SaveAs
Allow Allow
Write/Save Allow Allow
In this scenario, because permissions are set the sameway for both projects andworkbooks, if you want to apply project-level permissions changes to all workbookswithin the project, you can selectAssign Permissions to Contentswhile on thePermissions: Project page.
Allow users to save new but not overwrite existing workbooks
Permission For theproject
For appropriate work-books in the project
Web Edit Allow AllowDownload/SaveAs
Allow Allow
Write/Save Allow Deny
Important: In this scenario, permissionsmust be set manually on each workbook. If youselectAssign Permissions to Contents as described inAllow users to savechanges to existing and new workbooks above, project permissions overwrite theworkbook permissions, thereby granting users access to save changes to existingworkbooks.
- 212 -
Permissions for views within workbooks
Permissions for views in workbooks are inherited from the workbook permissionswhen a userpublishes a workbook from Tableau Desktop.
If a user selectsShow sheets as tabswhen publishing a workbook from Tableau Desktop orsaving it on Tableau Server, the workbook permissions override the permissions on individualviews, until the workbook is saved again without tabs.
For more information, seePermissions Reference on page 197 and also the knowledgebase article Creating Project-Based Permissions.
Example: Disable Web AuthoringIf you want users to be able to view published workbooks on Tableau Server but not access theserver authoring environment, you can use a site-level setting to disable authoring.
For example, youmight have a select group of data analysts who use Tableau Desktop to buildand publish workbooks, and a group of salesmanagers working in the field who do not useTableau Desktop or perform data analysis, but need to view and share the publisheddashboards through the web environment.
To disable authoring, complete the following steps.
1. In a web browser, sign in to the server environment as an administrator.
2. On the Admin tab, selectSites.3. On the Sites page, select the check box for the site on which you want to disable
authoring, and then clickEdit.
4. In the Edit Site dialog box, clear the check box forAllow web authoring for this site,and clickOK.
- 213 -
On the Sites page, you can confirm that web authoring is disabled.
5. If your site is already in production, and you want the change to take effect immediately,restart the server.
Alternatively, you can wait for the server session caching to expire. Until it does, usersmight have authoring access if they see an Edit link on a view, or if they enter the URL forthe view’s edit mode. For example, they bookmarked the URL while they had the viewopen for editing.
If you disable web authoring while creating a new site, no cached sessions exist, and thesetting takes effect immediately.
- 214 -
Manage OwnershipWhen you publish a data source or workbook on Tableau Server or when you create a project,you become its owner. Ownership can be changed. For example, if an employee who is theoriginal owner leaves, the administrator can reassign ownership to another user. Once youchange ownership, the original owner has no special connection to the item, and their ability toaccess it is determined by their Tableau Server permissions.
You cannot delete a Tableau Server user if the user owns any items.When you attemptto delete the user, their license level is set to Unlicensed. Youmust first change theownership of the items and then delete the user. For more information, see Deleting aUser from Tableau Server.
Your ability to change or be given ownership depends on your permissions and yourrelationship to the item:
Item type Who can change own-ership
Who can be given ownership
Projects system administrator
site administrator
system administrator
site administratorWorkbooks andData Sources
system administrator
site administrator
project leader for the projectthat contains the item
owner of the item
system administrator
site administrator
member of the site that contains the item,with a license other thanGuest
See the following topics for more information:
Change Owner for WorkbooksBy default, the publisher of a workbook is its owner. Administrators, project leaders, and thecurrent owner of the workbook can change the workbook's ownership. The new owner mustbe a system administrator or a site administrator or have a license level other thanGuest on thesame site as the workbook.
To change the owner of a workbook:
1. On the Content tab, select Workbooks.2. On theWorkbooks page, select one or more workbooks, and then clickChange Owner:
- 215 -
3. Type the name of a user or select a user from the list:
4. ClickOK to change the owner.
Change Owner for a Data SourceBy default, the publisher of a data source is its owner. Administrators, project leaders, and thecurrent data source owner can change its owner. The new owner must be a system or siteadministrator or have a license level other thanGuest on the same site as the data source.
To change the owner for a data source:
1. On the Content tab, select Data Sources.2. Select one or more data sources, and then clickChange Owner.
- 216 -
3. Type the name of a user or select a user from the list:
4. ClickOK to change the owner.
Change Owner for a ProjectBy default, the creator of a project is its owner. Administrators can change the project's owner.The new owner must be a system administrator or an administrator for the project's site.
To change the owner for a project:
1. On the Admin tab, selectProjects.2. Select one or more projects, and then clickChange Owner:
- 217 -
3. Type the name of a user or select a user from the list:
4. ClickOK to change the owner.
- 218 -
SecurityThere are four main components to security in Tableau Server:
AuthenticationAuthentication establishes a user’s identity. This is done to prevent unauthorized access toTableau Server and allow for a personalized user experience. Tableau Server supports fourtypes of authentication:
l Active Directory: Authenticates Tableau Server users based on their Windowscredentials.
l Local Authentication: Uses the internal authenticationmechanism provided withTableau Server.
l SAML: Uses an external identity provider (IdP) to authenticate Tableau Server users.l Trusted Authentication: Handles authentication through a trust relationship betweenTableau Server and one or more web servers.
Whether to use Active Directory or Local Authentication is a choice youmake during TableauServer Setup. After Setup, you can’t switch between the two. To switch authentication types,uninstall Tableau Server (your data will be preserved) and rerun Setup.
You can also choose to configure SAML during Setup, however, that is not the only time youcan configure it. When SAML is handling user authentication, Active Directory or LocalAuthentication becomeswhat you're using tomanage, not authenticate, your Tableau Serverusers. SAML can be enabled or disabled without having to uninstall Tableau Server and rerunSetup.
Active DirectoryWhen Active Directory is used for user authentication, all usernames and passwords aremanaged by Active Directory. When a user enters their credentials to sign in to TableauServer, Tableau passes them to the Active Directory server. It does not participate in theauthentication process—although it does store usernames (but not passwords) in itsrepository.
With Active Directory user authentication, administrators can also automatically sign in usersbased on their currentWindows credentials (Enable automatic login). Thismeans that theuser’s credentials are being passed from their local computer, not from another system orportal that theymay have signed in to.
For example, if a user signs in to their local computer as ‘MSmith’ and then signs in to aSharePoint portal as ‘Mary’, the credentials passed to Tableau Server will be for ‘MSmith’. Touse the credentials from the SharePoint site (‘Mary’) for automatic sign-in, the SharePointportal must use the Tableau web part with trusted authentication.
- 219 -
Administrators can synchronize groupswith Active Directory either manually orprogrammatically, using tabcmd. SeeSynchronize an Active Directory Group on page 90and syncgroup group-name in tabcmd Commands on page 322 for more information.
Local AuthenticationWhen Local Authentication is used for user authentication, Tableau Server manages users,groups, passwords and the entire authentication process. User lists can easily be imported tothe Tableau Server andmost user management functions can be performed programmaticallythrough tabcmd on page 319. Users can either manually sign in by entering their credentialswhen prompted or, when accessing content in a portal, via transparent trusted authentication.
SAMLWhen SAML is used for user authentication, an external identity provider (IdP) authenticatesTableau Server users. You still need to use either Active Directory or Local Authentication tomanage your Tableau Server users, add them to Tableau Server, etc., but the authenticationpiece is handled by the IdP.When users sign in to Tableau Server using SAML, the sign-inthey see belongs to the IdP, not Tableau Server. SeeSAML on page 290 for information onhow to set up SAML at your site.
Trusted AuthenticationTrusted authenticationmeans that you have set up a trusted relationship between TableauServer and one or more web servers. For example, youmay have your corporate wiki usetrusted authentication to show dashboards to employeeswho are already signed onto the wiki,without requiring another login.
When Tableau Server receives requests from a trusted web server it assumes that the webserver has already handled whatever authentication is necessary. Tableau Server receives therequest with a redeemable token or ticket and presents the user with a personalized viewwhich takes into consideration the user’s role and permissions.
See Trusted Authentication on page 271 for information on how to set up trustedauthentication at your site.
AuthorizationAuthorization is what a user can access and do once he or she is authenticated. In Tableau,authorization is handled by the following:
l Roles and permissions: Define specific capabilities that users can or cannot performon certain objects in Tableau. A role is a set of permissions that administrators can useas-is or customize. SeeWork with Permissions on page 188 for details.
l Licensing and user rights: Control themaximum set of permissions that a user canhave. See Licenses and User Rights on page 82 andAllow or Deny User Rightson page 86.
- 220 -
While the above items control which actions a user can perform and on what, they do notcontrol which data will appear inside a view. The data a user sees is controlled by your datasecurity choices.
Initial PermissionsThe initial permissions for a project are copied from the Default project. The initial permissionsfor a workbook are copied from the permissions for its project. The initial permissions for a vieware copied from the permissions of its workbook. This is a one-time copy of the parent’spermissions. Changes to the parent’s permissions are not automatically applied to the childrenunless the new permissions are actively assigned to the contents.
Any item can have permissions that differ from the parent. For example, a groupmight nothave permission to see Project X, but it may have permission to see a view that’s published toProject X. Tableau Server does not support hierarchical object permissions; however, it doesprovide an inheritancemodel for users and groups. If a user does not have a permissionexplicitly set to Allow or Deny, the setting will be inherited from the groups the user belongs to.
Permissions and the Default ProjectIf Tableau Server is deployed in an open environment where knowledge and informationsharing is key, then you should consider setting the permissions for the Default project toinclude theAll Users group, with its role set to Interactor. Users will be able to automaticallypublish to and consume content from new projects.
If Tableau Server is deployed in a restrictive environment where data security and accesscontrol is key, then consider emptying the permissions for the Default project: Delete thepermissions for all users and groups. Users and groupswill need to be explicitly grantedpermission to publish and consume content in new projects.
Data SecurityTableau provides several ways for you to control which users can see which data. For datasources that connect to live databases, you can also control whether users are prompted toprovide database credentials when they click a published view. The following three optionswork together to achieve different results:
l Database login account:When you create a data source that connects to a livedatabase, you choose between authenticating to the database throughWindowsNT orthrough the database’s built-in securitymechanism.
l Authentication mode:When you publish a data source or a workbookwith a livedatabase connection, you can choose anAuthentication mode. Whichmodes areavailable depends on what you choose above.
l User filters: You can set filters in a workbook or data source that control which data aperson sees in a published view, based on their Tableau Server login account.
The table below outlines some dependencieswith the above options:
- 221 -
Database Connection Options Data Security QuestionsDatabaselogin accountuses...
Authenticationmode
Is data-basesecuritypossibleperTableauServeruser?
Are user fil-ters the onlyway torestrictwhich dataeach usersees?
Arewebcachessharedamongusers?
Window NTIntegratedSecurity (Win-dowsAuthentication)
Server Run Asaccount
No Yes Yes
Impersonate viaserver Run Asaccount
Yes No* No
Username andPassword
Prompt user: Viewersare prompted for theirdatabase credentialswhen they click a view.Credentials can besaved.
Yes No No
Embeddedcredentials: The work-book or data sourcepublisher can embedtheir database cre-dentials.
No Yes Yes
Impersonate viaembedded password:Database credentialswith impersonate per-mission are embed-ded.
Yes No* No
* Because it can create unexpected results, Tableau recommends that you not use thisauthenticationmodewith user filters.
User filters, the embedded credentials option and the impersonationmodes have similareffects—when users click a view, they are not prompted for database credentials and they seeonly the data that pertains to them. However, user filters are applied in the workbook byauthors, and the impersonation authenticationmodes rely on security policies defined byadministrators in the database itself.
Some of the options described above require configuration steps that must happen duringTableau Server Setup or before you publish a workbook or data source. See the followingtopics for more information:
- 222 -
l Run As User on page 298l SQL Server Impersonation on page 307l Embedded Credentials
l Saved Passwords
Network SecurityThere are threemain network interfaces in Tableau Server:
l Client to Tableau Server: The client can be a web browser, Tableau Desktop, or thetabcmd utility.
l Tableau Server to your database(s): To refresh data extracts or handle live databaseconnections, Tableau Server needs to communicate with your database(s).
l Server component communication: This applies to distributed deployments only.
Client to Tableau ServerA Tableau Server client can be a web browser, Tableau Desktop, or tabcmd. Communicationsbetween Tableau Server and its clients use standard HTTP requests and responses. TableauServer can also be configured for HTTPS (seeSSL on page 14). When Tableau Server isconfigured for SSL, all content and communications between clients are encrypted using SSL,and the HTTPS protocol is used for requests and responses.
Passwords are communicated from browsers and tabcmd to Tableau Server using 512-bitpublic/private key encryption. Tableau Server sends a public key to the browser, which usesthe key to encrypt the password for transmission. Each encrypted transmission uses a key onetime before it is discarded. Thismeans that passwords are always secured regardless of theuse of SSL. If SSL is enabled, SSL encryption is used in addition to the 512-bit public keyencryption of passwords.
Tableau Server to Your DatabaseTableau Server makes dynamic connections to databases to process result sets and refreshextracts. It uses native drivers to connect to databaseswhenever possible and relies on ageneric ODBC adapter when native drivers are unavailable. All communications to thedatabase are routed through these drivers. As such, configuring the driver to communicate onnon-standard ports or provide transport encryption is part of the native driver installation. Thistype of configuration is transparent to Tableau.
Server Component CommunicationThere are two aspects to communication between Tableau Server components in a distributedserver installation: trust and transmission. Each server in a Tableau cluster uses a stringenttrust model to ensure that it is receiving valid requests from other servers in the cluster.Computers in the cluster running a gateway process accept requests from 3rd parties (clients),
- 223 -
unless they are fronted by a load balancer, in which case the load balancer receives therequests. Servers not running a gateway process only accept requests from other trustedmembers of the cluster. Trust is established by a whitelist of IP address, port, and protocol. Ifany of these are invalid, the request is ignored. All members of the cluster can communicatewith each other. With the exception of license validation and accessing the repository,transmission of all internal communication is performed via HTTP.
When a user stores credentials for external data sources on Tableau Server, they are storedencrypted in Tableau Server's internal database.When a process uses those credentials toquery the external data source, the process retrieves the encrypted credentials from theinternal database and decrypts them in process.
Protect Credentials for Cloud DataFor some cloud-based data sources, an alternative to storing sensitive database credentials inTableau Server is to establish a limited-purpose trust relationship between Tableau and thedata-source provider. Through this relationship, you can access your data while keeping yourcredentials secure with the data-source provider.
To establish this type of relationship, you authorize Tableau to access your cloud data. Thecloud data provider then sends Tableau a limited-purpose access token, which uniquelyidentifies requests from Tableau and allows Tableau to access the data on your behalf.
Tableau workswith these protected connections as specified in theOAuth 2.0 open-authorization standard. Using OAuth connections provides the following benefits:
l Security: Your sensitive database credentials are never known to or stored in TableauServer, and the access token can be used only by Tableau.
l Convenience: Instead of having to embed your data source ID and password inmultiple places, you can use the token provided for a particular data provider for allpublished workbooks and data sources that access that data provider.
In addition, for live connections to Google BigQuery data, each workbook viewer canhave a unique access token that identifies the user, rather than sharing a single username and password credential.
Protected authentication is available for Google BigQuery, Google Analytics, andSalesforce.com data sources.
Overview of the OAuth ProcessThe following steps describe a workflow in the Tableau environment that calls the OAuthprocess.
1. You take an action that requires access to a cloud data source.
For example, you open a workbook that’s published to Tableau Server.
2. Tableau directs you to the hosted data provider’s sign-in page. The information that is
- 224 -
sent to the hosted data provider identifies Tableau as the requesting site.
3. When you sign in to the hosted data source, it prompts you to confirm your authorizationfor Tableau Server access to the data.
4. Upon your confirmation, the data-source provider sends an access token back toTableau Server.
5. Tableau Server presents your workbook and data to you.
The following are other workflows that can use theOAuth process:
l Creating a workbook and connecting to the data source from Tableau Desktop or fromTableau Server.
l Publishing a data source from Tableau Desktop.
Managing CredentialsUsers canmanage their own access tokens in user preferences, or you can choose to allowonly administrators and users with the Data Source Connector role tomanage access tokensacross data sources and connections.
The following applies whether an access token is used as an embedded credential with apublished data source or used for live connections to Google BigQuery data:
l When Tableau Server requests data through a connection represented by an accesstoken, the data-source provider confirms authorized Tableau access through the token,and then returns the requested data. You do not need to provide credentials each timeyou connect.
l If the token is used as an embedded credential with a published data source, you cancreate new workbooks that connect to that data from Tableau Desktop or TableauServer, without having to sign in each time to access the data.
- 225 -
l Access tokens are valid until a user or data provider revokes them.
Note It is possible to exceed the number of access tokens a data source providerallows. If that's the case, when a new token is created, the data provider useslength of time since last access to decide which token to invalidate tomake roomfor the new one. The data provider can also invalidate a token for other reasons.For example, an administrator might revoke all application access.
- 226 -
PerformanceEvery server environment is unique and there aremany variables that impact performance.Variables include hardware details, such as disk speed, memory, and cores; the number ofservers in your deployment; network traffic; usage factors such asworkbook complexity,concurrent user activity, and data caching; Tableau Server configuration settings, such as howmany of each server process you’re running; and data considerations—such as data volume,database type, and database configuration. Because of this complexity, there is no singleformula for improving server performance, but there are some basic guidelines you can follow.Use the topics below for more information:
General Performance Guidelines
Hardware and SoftwareUse a 64-bit operating system and the 64-bit product: Although Tableau Server runswellon 32-bit Microsoft operating systems, for the best performance, choose a 64-bit operatingsystem and install the 64-bit version of Tableau Server.
Add more cores and memory: Regardless of whether you’re running Tableau Server onone computer or several, the general rule is that more CPU cores andmore RAMwill give youbetter performance. Make sure youmeet Tableau Server’s recommended hardware andsoftware requirements and seeWhen to Add Workers & Reconfigure on the next page toassesswhether you should add additional machines. If you are running Tableau Server in avirtual environment, use your VM's best practices for vCPU allocation in relation to the numberof physical CPU cores on the VMhost.
ConfigurationSchedule refreshes for off-peak hours: Backup tasks tend to stall other background tasksuntil the backup is completed. Use theBackground Tasks on page 159 administrative view tosee your refresh and backup task schedules.Your refresh tasks should be scheduled for off-peak hours that don't overlap with your backup window.
Look at caching: Caching helps Tableau Server respond to client requests quickly, especiallyfor views that connect to live databases. Confirm thatRefresh Less Often on the DataConnections tab of the Configuration dialog box is selected.
Consider changing two session memory settings:
l VizQL session timeout limit: The default VizQL session timeout limit is 30minutes.Even if a VizQL session is idle, it is still consumingmemory and CPU cycles. If you canmake do with a lower limit, use tabadmin on page 338 to change the vizqlserv-er.session.expiry.timeout setting .
l VizQL clear session: By default, VizQL sessions are kept in memory even when a usernavigates away from a view. This consumes a good deal of sessionmemory. Instead,
- 227 -
you can end sessionswhen usersmove away from a view by changing the value of thevizqlserver.clear_session_on_unload setting to true (default is false).
Assess your process configuration: Tableau Server is divided into six differentcomponents called server processes.While their default configuration is designed to work for abroad range of scenarios, you can also reconfigure them to achieve different performancegoals. Specifically, you can control on which computers the processes run and how many arerun. See Improve Server Performance on the next page for guidelines for one-, two-, andthree-node deployments.
When to Add Workers & ReconfigureTableau Server can scale up and out as your needs and requirements evolve. Here are someguidelines to help you figure out whether it’s time to addmore nodes to your system,reconfigure the server, or both:
l More than 100 concurrent users: If your deployment is user-intensive (>100simultaneous viewers), it’s important to have enough VizQL processes—but not somany that they exceed your hardware’s capacity to handle them. Also, enabling theTableau Server Guest User account can increase the number of potential simultaneousviewers beyond the user list youmay think you have. The administrative view UserActivity on page 157 can help you gauge this. For tips on how to configure or scale yourdeployment, see Improve Server Performance on the next page.
l Heavy use of extracts: Extracts can consume a lot of memory and CPU resources.There’s no onemeasurement that qualifies a site as extract-intensive. Having just a few,extremely large extracts could put your site in this category, as would having verymanysmall extracts. Extract heavy sites benefit from isolating the data engine process on itsownmachine. Refer to Improve Server Performance on the next page for guidelines.
l Frequent extract refreshes: Refreshing an extract is a CPU-intensive task. Siteswhere extracts are frequently refreshed (for example, several times a day) are oftenhelped bymore emphasis on the background process, which handles refresh tasks. UsetheBackground Tasks on page 159 administrative view to see your current refreshrate, then see Improve Server Performance on the next page for details on how toscale.
l Troubleshooting performance: If views are slow to load or server performance isgenerally slow, there could be several causes. SeeGeneral Performance Guidelineson the previous page aswell as Improve Server Performance on the next page.
l Downtime potential: If your server system is consideredmission critical and requires ahigh level of availability, you can configure it so there’s redundancy for the serverprocesses that handle extracts, the repository, and the gateway. Refer toHighAvailability on page 45 for details.
- 228 -
Improve Server PerformanceUse the topics below for guidance on how to improve the performance of deployments that areextract-intensive, user-intensive, or both:
What’s your goal?
One-MachineExample:Extracts
How ManyProcesses to Run
Two-MachineExample:Extracts
Where to Configure Processes
Two-MachineExample:Viewing
Optimizing the Extracts andWorkbooks
ThreeMachineExample:Extracts& View-ing
Assessing View Responsiveness on page 230
What’s your goal?Optimizing for ExtractsThe data engine process stores extracts and answers queries; the background processrefreshes extracts. Because both are demanding of CPU resources, the best approach toimproving performance for an extract-intensive deployment is to isolate these two processesfrom one another, and from the other server processes. Thismay take threemachines. If youdon’t have threemachines to work with, there are still strategies you can use (see thedeployment examples below).
Optimizing for Users and ViewingThe VizQL server process handles loading and rendering views for Tableau Server users. Ifyou are trying to optimize your deployment for a high number of users and a lot of viewinteraction, this is the process you should focus on.
- 229 -
HowMany Processes to RunThis topic assumes that you are running the 64-bit version of Tableau Server on a 64-bitoperating system. In this situation, two instances of each process shouldmeet your needs. Ifyour machine onlymeets theminimumRAM requirement for Tableau Server, which is 8 GB,your limit should be one instance of each process.
Background ProcessA single background process can consume 100% of a single CPU core, and sometimes evenmore for certain tasks. As a result of this, the total number of instances you should run dependson themachine’s available cores—aswell as on what you’re trying to improve. The deploymentexamples below uses N to represent themachine’s total number of cores, and each suggests adifferent strategywhere the background process is concerned.When in doubt, start with thelow end of the suggested range and assess performance before increasing the number.
Data Engine and Repository ProcessesThere are scenarios where the data engine process should be isolated on its own node—suchas if you are trying to improve an extract-intensive deployment and you want to emphasizequeryingmore than extract refreshes. The deployment examples provide specifics. Becausethe data engine stores real-time data, transferring it is amulti-phased procedure.Move theData Engine and Repository Processes on page 34 describes how to do it.
Another reason to isolate the data engine (and/or the repository) is to minimize yourdeployment’s potential for downtime. SeeHigh Availability on page 45 for details. Unlessyou’re configuring for high availability, the repository can usually remain on the primaryTableau Server.
Where to Configure ProcessesYou configure the type and number of processes anymachine is running using the TableauServer Configuration dialog box. If you are adding new machines as part of yourreconfiguration, theymust already have TableauWorker software installed on them. Refer toInstall and Configure Worker Servers on page 40 for steps.If you are reconfiguring the processes on your primary or standalone Tableau Server, seeReconfigure Processes on page 23.
Optimizing the Extracts and WorkbooksFast server performance with extracts is partly a function of the extracts and workbooksthemselves.Workbook authors can help improve server performance by keeping the extract’sdata set short, through filtering or aggregating, and narrow, by hiding unused fields. Use theTableau Desktop optionsHide All Unused Fields andAggregate data for visibledimensions to do this. For steps, see Creating an Extract (Tableau Desktop help). Forgeneral tips on building well-performing workbooks, search for “performance” in the TableauDesktop help. To see how workbooks perform after they've been published to Tableau Server
- 230 -
you can create a performance recording. SeeCreate a Performance Recording on page240 for details.
Assessing View ResponsivenessWhen a user opens a view, the components of the view are first retrieved and interpreted, thendisplayed in the user's web browser. For most views, the display rendering phase occurs in theuser's web browser and inmost cases, this yields the fastest results and highest level ofinteractive responsiveness. Handlingmost interactions in the client web browser reducesbandwidth and eliminates round-trip request latencies. If a view is very complex, TableauServer handles the rendering phase on the server instead of in the client web browser—because that generally results in the best performance. If you find that views aren't asresponsive as you'd like, you can test and change the threshold that causes views to berendered by the server instead of in the client web browser. SeeAbout Client-SideRendering on page 235 for more information.
One-Machine Example: ExtractsA 64-bit Tableau Server installation with heavy extract usage can run on a single 64-bitmachine configured as follows:
- 231 -
The above configuration would look like the following on the Tableau Server Maintenancepage:
Configuration Notes:
l Run 2 VizQL server processes.
l Calculate the least number of background processes to run by taking themachine’s totalnumber of cores and divide it by 4. To determine themaximumnumber, divide by 2.
l Both the background and data engine processes are CPU-intensive and the aboveconfiguration balances them.
l Scheduling extract refreshes for off-peak times helps the data engine and backgroundprocesses not compete with one another for system resources.
Two-Machine Example: ExtractsHere’s how you can configure a two-machine Tableau Server deployment so that it can handleheavy extract usage. Themost important thing to note in this example is that the data engineprocess is isolated from the background processes.
- 232 -
With the above configuration, the Status table on theMaintenance page would look like this:
Configuration Notes:
l Once you go from a one- to two-machine deployment, your first server becomes theprimary Tableau Server.
l Run 2 VizQL server processes on eachmachine.
l To figure out theminimumnumber of background processes to run on the primaryTableau Server, take themachine’s total number of cores and divide it by 4. For themaximumnumber, divide by 2.
l Moving the data engine from the primary Tableau Server to the worker is amulti-phasedprocedure. SeeMove the Data Engine and Repository Processes on page 34 forsteps.
Two-Machine Example: ViewingA two-machine deployment with light extract usage and heavier viewing can be configured asfollows:
- 233 -
The Status table for the above configuration would look like this:
Configuration Notes:
l Run 2 VizQL server processes on eachmachine.
l Aminimumof 2 background processes should be run on the primary Tableau Server.Themaximumnumber you should run is equal to themachine’s total number of cores.
l In a deployment where extracts are refreshed infrequently, the data engine andbackground processes can be on the samemachine as the other processes.
l If extract refresh jobswill be only run during off hours, many background processes canbe placed on eachmachine tomaximize their parallelism.
l The number of machines in the cluster is solely determined by the total number of coresandmainmemory available.
Three-Machine Example: Extracts & ViewingA three-machine configuration is the recommendedminimumnumber of machines to achievethe best performance if you have both a high amount of extract refreshing and usage, and ahigh number of concurrent users.
- 234 -
Here’s the Status table for the above configuration:
- 235 -
Configuration Notes:
l Run 2 VizQL Server processes.
l The background processes are on their ownmachine so that their work does notcompete with that of the other processes. Because themachine is dedicated tobackground processes and they can consume 100% of the CPU resources, the low endof the suggested range equals the total number of cores. Depending on the size of thedata being refreshed, it’s possible for some deployments to run up to twice asmanybackground processes than cores and still obtain parallel speed-up.
l Because the data engine process can consume all CPU resources on amachine, it isisolated on its ownmachine.
l The user loads for the application server and data server processes can typically behandled by 1 process each but they are set to 2 to provide redundancy.
l Under most conditions, the primary Tableau Server and the data engine will not be abottleneck for the system’s overall throughput as long as sufficient CPU cycles exist forthem. To increase viewing capacity, addmachines dedicated to the VizQL Serverprocess. To increase capacity for refreshing extracts, addmachines dedicated to thebackground process.
About Client-Side RenderingBefore a view'smarks and data are displayed in a client web browser, they are retrieved,interpreted, and rendered. Tableau Server can perform this process in the client web browseror on the server. Client-side rendering is the default mode because handling the rendering andall interaction on the server can result in more network data transfer and round-trip delays.With client-side rendering, most view interactions are faster, because they are interpreted andrendered right there in the client.
Some views, however, aremore efficiently rendered on the server where there'smorecomputing power. Server-side renderingmakes sense for a view that is complex to the extentthat image files take up significantly less bandwidth than the data used to create the images.Also, because tablets usually havemuch slower performance than PCs, they can handle lessview complexity. There are caseswhere a view opened from a PC's web browser might beclient-rendered but the same view opened from a tablet's web browser is server-rendered.
Tableau Server is configured to automatically handle all of these situations using TheThreshold Calculation on the next page as the trigger for rendering a view on the serverinstead of in the web browser. As the administrator, you can test or fine tune this setting forboth PCs and tablets. See the topics below for more information.
- 236 -
Requirements
l Supported browsers: Client-side rendering is supported in Internet Explorer version9.0 or higher, Firefox, Chrome, and Safari. All of these web browsers include the HTML5 <canvas> element, which is used by client-side rendering.
l Polygons, custom shapes, and the page history feature: If a view uses polygons,custom shapes, or the page history feature, server-side rendering is performed, even ifclient-side rendering is otherwise enabled.
The Threshold Calculation
When client-side rendering is enabled, Tableau Server uses a calculation to determine theview's complexity. If the complexity value exceeds 100 (for PC browsers) or 20 (for tabletbrowsers), the view is rendered on the server instead of in the web browser. Here's thecalculation:
(# of marks) + 3(# of headers) + 3(# of annotations) + 3(# of ref-erence lines) = view complexity
For example, if you have a view with 2,000marks, 150 headers (you can sometimes determinethis by adding the number of rows and columns in a view), 1 annotation, and 1 reference line,your equation would be:
2,000 + 3(150) + 3(1) + 3(1) = 2,456
Now take the current threshold value and divide it by 100, thenmultiply it by 5,000 (dividing thethreshold by 100 is a normalization andmultiplying by 5,000 is Tableau's scaling factor).Assuming a current threshold value of 100, the equation would be as follows:
100/100 * 5,000 = 5,000
Compare the two sums. Knowing that 5,000 represents a complexity of 100, you can see that2,456 represents about half the complexity (49). Therefore, to force server-side rendering forthis particular view on a PC browser, you would need to set that threshold to 48. Keep inmindthat interactions such as filteringmay change the complexity of the view, and a sessionmayswitch renderingmodeswhenever the view's complexity changes.
See the topics below for details on how to test and configure client-side rendering.
Test with the URL Parameter
Tableau Server is configured to perform client-side rendering by default, as long as therequirements aremet. To test server-side rendering on a session basis, type?:render=false at the end of the view's URL. For example:
http://localhost/views/Supplies/MyView?:render=false
If client-side rendering is disabled on Tableau Server, enter ?:render=true to enable it forthe session:
- 237 -
http://localhost/views/Supplies/MyView?:render=true
You can also test particular complexity thresholds on individual views to see if it’s appropriate toadjust the server-wide threshold for your server and network conditions. For example, youmayfind that lower complexity (such as 80) or higher complexity (such as 120) tipping points resultin more responsiveness to user interactions. To test a threshold, you can keep the server’sdefault configuration (client-side-rendering enabled) and enter the test threshold number at theend of the view's URL. For example:
http://localhost/views/Supplies/MyView?:render=80
Configure with the tabadmin set Options
You can use the tabadmin options vizqlserver.browser.render to disable or enableclient-side rendering and vizqlserver.browser.render_threshold andvizqlserver.browser.render_threshold_mobile to change the thresholds forclient-side rendering. See tabadmin set options on page 358 for details.
Tableau Server ProcessesThere are six Tableau Server processeswhose default configuration you can change toachieve different results. The topics Improve Server Performance on page 228 andHighAvailability on page 45 describe some of the approaches you can take. High-level status foreach process is displayed on the server’sMaintenance page andmore detailed informationrelated to some of the processes—such as the background process—is in theAdministrativeViews on page 155 topic.Architecturally, the 64-bit version of Tableau Server uses native, 64-bit processes; the 32-bitversion of Tableau Server uses 32-bit processes. The exception is the data engine. If the 32-bitversion of Tableau Server is installed on a 64-bit operating system, the 64-bit version of thedata engine process is used.
For information on log files generated by these processes, seeServer Log File Locations onpage 379.
Process File Name Purpose Multi-Threaded?
PerformanceCharacteristics
applicationserver
wgserver.exe Handles the webapplication,supports browsingand searching
Yes Only consumesnoticeable resourcesduring infrequentoperations, likepublishing a workbookwith an extract, orgenerating a static imagefor a view. Its load can becreated by browser-based interaction and bytabcmd.
- 238 -
Process File Name Purpose Multi-Threaded?
PerformanceCharacteristics
background backgrounder.exeExecutes servertasks, includingextract refreshes,‘Run Now’ tasks,and tasks initiatedfrom tabcmd
No A single-threadedprocesswheremultipleprocesses can be run onany or all machines in thecluster to expandcapacity. Thebackgrounder normallydoesn’t consumemuchprocessmemory, but itcan consumeCPU, I/O,or network resourcesbased on the nature ofthe workload presentedto it. For example,performing large extractrefreshes can usenetwork bandwidth toretrieve data. CPUresources can beconsumed by dataretrieval or complextabcmd tasks.
data engine tdeserver64.exe
tdeserver.exe
Stores dataextracts andanswers queries
Yes The data engine'sworkload is generated byrequests from the VizQLServer process. It is thecomponent that loadsextracts intomemoryand performs queriesagainst them. Memoryconsumption is primarilybased on the size of thedata extracts beingloaded. The 64-bit binaryis used as the default on64-bit operatingsystems, even if 32-bitTableau Server isinstalled. The dataengine ismulti-threadedto handlemultiplerequests at a time.
- 239 -
Process File Name Purpose Multi-Threaded?
PerformanceCharacteristicsUnder high load it canconsumeCPU, I/O, andnetwork resources, all ofwhich can be aperformance bottleneckunder load. At high load,a single instance of thedata engine canconsume all CPUresources to processrequests.
data server dataserver.exe Handlesconnections toTableau Serverdata sources
Yes Because it’s a proxy, it’snormally only bound bynetwork, but it can bebound byCPU withenough simultaneoususer sessions. Its load isgenerated by browser-and Tableau Desktop-based interaction andextract refresh jobs forTableau Server datasources.
repository postgres.exe Tableau Serverdatabase, storesworkbook anduser metadata
n/a Normally consumes fewresources. It canbecome a bottleneck inrare cases for very largedeployments (thousandsof users) whileperforming operationssuch as viewing allworkbooks by user orchanging permissions.
VizQLServer
vizqlserver.exe Loads andrenders views,computes andexecutes queries
Yes Consumes noticeableresources during viewloading and interactiveuse from aweb browser.Can be CPU bound, I/Obound, or networkbound. Process load canonly be created bybrowser-based
- 240 -
Process File Name Purpose Multi-Threaded?
PerformanceCharacteristicsinteraction. Can run outof processmemory.
Create a Performance RecordingWith the Performance Recording feature in Tableau, you can record performance informationabout key events as you interact with workbooks. You then view performancemetrics in aperformance workbook that Tableau creates automatically. The steps you follow to create andview performance recording vary somewhat between Tableau Desktop and Tableau Server.However, the resulting performance workbooks have the same format in both TableauDesktop and Tableau Server.
Use performance workbooks to analyze and troubleshoot performance issues pertaining todifferent events that are known to affect performance, including:
l Query executionl Geocodingl Connections to data sourcesl Layout computationsl Extract generationl Blending datal Server blending (Tableau Server only)
Tableau support may request that you create performance workbooks as they assist you withdiagnosing performance issues.
To Create a Performance Recording in Tableau ServerThe server administrator determineswhether to enable performance recording at the site level.By default, performance recording is not enabled in the default site, or in any site you create. Toenable performance recording for a site, follow these steps:
1. Choose the Admin button in Tableau Server.
2. Choose Sites.
3. Select a site.
4. Choose Edit.
5. In the Edit Site dialog box, select Allow Performance Recording.
6. ChooseOK.
You start performance recording for a specific view by adding ?:record_performance=yes tothe url. For example:
- 241 -
http://localhost/views/Variety/BaseballStatistics?:record_performance=yes
When Tableau Server displays the view, it appends "#<n>" to the end of the URL. This is asession id. You need to add ?:record_performance=yes before the session id:http://localhost/views/Variety/BaseballStatistics?:record_performance=yes#1
The visual confirmation that recording has started is aShow Performance Recordingcommand in the toolbar:
ChooseShow Performance Recording to open a performance workbook, which is an up-to-the-minute snapshot of performance data. You can continue taking additional snapshots asyou continue working with the view; the performance data is cumulative. Once you page awayfrom the view, or remove ?:record_performance=yes from the url, recording stops.
Interpret a Performance RecordingA performance recording workbook is a Tableau dashboard that contains three views:Timeline, Events, andQuery.For information on how to create a performance recording in Tableau Server, seeCreate aPerformance Recording on the previous page.
TimelineThe uppermost view in a performance recording dashboard shows the events that occurredduring recording, arranged chronologically from left to right. The bottom axis shows elapsedtime since Tableau started, in seconds.
In the Timeline view, theWorkbook,Dashboard, andWorksheet columns identify thecontext for events. TheEvent column identifies the nature of the event, and the final columnshows each event’s duration and how it compares chronologically to other recorded events:
- 242 -
EventsThemiddle view in a performance recording workbook shows the events, sorted by duration(greatest to least). This can help you identify where to look first if you want to speed up yourworkbook.
Different colors indicate different types of events. The range of events that can be recorded is:
l Computing layouts.
If layouts are taking too long, consider simplifying your workbook.
l Connecting to data source.
Slow connections could be due to network issues or issueswith the database server.
l Executing query.
If queries are taking too long, consult your database server’s documentation.
l Generating extract.
To speed up extract generation, consider only importing some data from the originaldata source. For example, you can filter on specific data fields, or create a sample basedon a specified number of rows or percentage of the data.
l Geocoding.
To speed up geocoding performance, try using less data or filtering out data.
l Blending data.
To speed up data blending, try using less data or filtering out data.
l Server rendering.
You can speed up server rendering by running additional VizQL Server processes onadditional machines.
QueryIf you click on anExecuting Query event in either the Timeline or Events section of aperformance recording dashboard , the text for that query is displayed in the Query section. Forexample:
- 243 -
Sometimes the query is truncated and you’ll need to look in the Tableau log to find the fullquery. Most database servers can give you advice about how to optimize a query by addingindexes or other techniques. See your database server documentation for details.
- 244 -
Embed Views into WebpagesYou can embed interactive views from Tableau Server into webpages, blogs, wikis, webapplications, and intranet portals. Embedded views update as the underlying data changes, oras their workbooks are updated on the server. Embedded views follow the same licensing andpermission restrictions used on the server. Generally, people loading a webpage with anembedded view must also have an account on Tableau Server. If you have a core-basedlicense you can alternatively select Enable Guest, which allows users to load the view withoutsigning in.
You can embed views the following ways:
l Use the Share embed code: The Share link at the top of each view provides embedcode that you can copy and paste into your webpage.
l Write your own embed code: You can enhance the embed code that Tableauprovides, or you can build your own code. Either way you can use parameters thatcontrol the toolbar, tabs, andmore.
l Use the Tableau JavaScript API: You can use Tableau JavaScript objects in yourownweb application code. For information, see JavaScript API on page 396.
For users to successfully authenticate when they click an embedded view, theirbrowsersmust be configured to allow third-party cookies.
Writing Embed CodeIf you’re writing your own embed code, you can take one of two approaches:
l Use Tableau JavaScript: This is the preferred approach. Use the embed code thatTableau generates as the starting point for your own code, adding or editing objectparameters that control the toolbar, tabs, andmore. The default embed code, whichrelies on a Tableau JavaScript file, is also the only way to control the load order ofmultiple embedded views.
l Specify the View URL: Embed a view using an Iframe or Image tag, where the sourceis the URL for the published view. Youmaywant to do this if you can’t use JavaScript onyour website. Theremay also be situationswhen all you can specify is an URL—such asif you're embedding a view using the SharePoint Page Viewer Web Part.
Regardless of the approach you take, youmust define a width and height if you are embeddinga view.
Tableau JavaScriptThe following code shows an example of embed code that is generated when you click Shareon a published view. Special characters in the host_url parameter are URL encoded, and
- 245 -
those in the site_root and name parameters are notated asHTML numeric characterreferences.
<script type='text/javascript' src-c='http://myserver/javascripts/api/viz_v1.js'></script><div class='tableauPlaceholder' style='width:800; height:600;'><object class='tableauViz' width='800' height='600' style-e='display:none;'>
<param name='host_url' value='http%3A%2F%2Fmyserver%2F' /><param name='site_root' value=/t/Sales' /><param name='name' value='MyCoSales/SalesScoreCard/'
/><param name='tabs' value='yes' /><param name='toolbar' value='yes' /></object></div>
The source for the <script> tag is the URL for the Tableau Server JavaScript file, viz_v1.js.The JavaScript file handles assembling the full URL of the view that’s displayed for your users.The name and site_root object parameters are the only required parameters; all otherparameters are optional. For examples, see the List of Embed Parameters below and the"Script Tag Examples" in theExamples on page 251 section.
View URL as the SourceHere’s an example of embedding the same view using an IFrame, where the source is the URLfor the view:
<iframe src="http://myserver/t/Sales/MyCoSales/SalesScoreCard?:embed=yes&:tabs=yes&:toolbar=yes" width="800" height-t="600"></iframe>
Youmust specify the embed URL parameter and can optionally include parameters thatcontrol the toolbar and revert options, among others. You can also add filters to the URL thatcontrol the specific data that showswhen a view is loaded. For examples, see the List ofEmbed Parameters below and the “Iframe Tag Examples” in theExamples on page 251section.
When you use the view’s URL for the iframe src attribute, exclude the hash tag (#) andnumber at the very end of the URL. For example, use MyCoSales/SalesScoreCardnot MyCoSales/SalesScoreCard#2.
List of Embed ParametersYou can embed a view using either an Iframe tag, which usesURL parameters, or aJavaScript tag, which uses object parameters. The following table lists both sets of parametersand how to use them.
- 246 -
ObjectPara-meter
URLPara-meter
Val-ues
Descrip-tion
Examples
cus-tomVie-ws
:cus-tomVie-ws
no Hides theRemembermychangesoption.
<param name="customViews" value-e="no"/>http://tabserver/views/Date-Time/DateCalc-s?:embed=yes&:customViews=no
- :embed yes Required forURL para-meter.Hides thetop nav-igation area,making theview blendinto yourweb pagebetter.
http://tabserver/views/Date-Time/DateCalcs?:embed=yes
filter - string Customizeswhat is dis-playedwhen theview opens.Filtering byURL para-meters isalso pos-sible.Referto the Iframetagexamples inAdd Filterson page 252and Filteron MultipleFields onpage 253.
<param name="filter" value-e="Team=Blue"/>
- :format pdf;png
Displays aview as aPDF or .pngfile.
http://t-abserver-/views/Sales/Q2?:format=pdf
- :high-dpi
fals-e
Renders a http://t-ableau-
- 247 -
ObjectPara-meter
URLPara-meter
Val-ues
Descrip-tion
Examples
view usingstandardDPI (dotsper inch) forhigh res-olution dis-plays anddevices.
server-/views/Sales/Q2?:highdpi=false
- :ori-ginal_view
yes If the nameparameterrefers to aworkbook orsheet URL(and doesnot explicitlyrefer to acustomview) includ-ing this para-meterdisplays theview as theoriginal viewwhen othercustomviews areavailable.
<param name="filter" value-e=":original_view=yes"/>
host_url
- string The servername as itappears inthe URL.
<param name="host_url" value-e="http://myserver.bigco.com/">
<param name="host_url"value="http://localhost/">
link-target
:link-target
string The targetwindowname forexternalhyperlinks.
<param name="linktarget" value="_blank"/>
http://tabserver/views/Date-Time/DateCalcs?:embed=yes&:linktarget=_blank
load-order
- num-ber
Whenmul-tiple viewsare embed-
<param name="load-order" value-e="2"/>
- 248 -
ObjectPara-meter
URLPara-meter
Val-ues
Descrip-tion
Examples
ded, thedefault loadorder is theorder inwhich theviews are lis-ted. Use thissetting tooverride thatorder. Neg-ative num-bers areallowed.
name - string Required forobject para-meter. Work-book andsheet nameand option-ally, a cus-tom view(user-name@-domain/[customviewname]). Ifyou refer tothe TableauServer URLto confirmthe value ofname,exclude thehash tag (#)and numberat the end ofthe URL.
<param name="name"value="MyCoSales/Sales"/>
<param name="name"value="MyCoSales/Sales/[email protected]/EastCoastSales"/>
path - string For trustedauthen-
<param name="path"value="trusted/Etdpsm_Ew6rJY-9kRrALjauU/views/workbookQ4/Sales
- 249 -
ObjectPara-meter
URLPara-meter
Val-ues
Descrip-tion
Examples
tication only,cannot beused withthe ticketparameter.Overridesvalue of thename para-meter and isused as theURL. Seethe TrustedAuthentic-ationexamples.
Q4"/>
http://tableauserver/trusted/Etdpsm_Ew6rJY-9kRrALjauU/views/workbookQ4/SalesQ4?:embed=yes&:tabs=yes
- :re-fresh
Re-rendersthe page.SeeRefreshData onpage 203 fordetails.
http://tabserver/views/Date-Time/DateCalc-s?:embed=yes&:refresh
:render true;fals-e;num-ber
If client-siderendering isenabled (thedefault), set-ting tofalseforcesserver-siderenderingfor the ses-sion. If cli-ent-siderendering isdisabled, set-ting to trueenables itfor the ses-sion. A num-ber can be
http://tabserver/views/Date-Time/DateCalcs?:render=false
- 250 -
ObjectPara-meter
URLPara-meter
Val-ues
Descrip-tion
Examples
used to testa complexitythreshold.SeeAboutClient-SideRenderingon page235.
- :revert all;fil-ter-s;sort-s;axe-s;shel-ves
Returns theitem to its ori-ginal state.
http://tabserver/views/Date-Time/DateCalc-s?:embed=yes&:revert=all
site_root
- string Required.The sitename. TheDefault sitevalue is null(value=""). If yourserver ismulti-siteand youwant to usetrustedauthen-tication, seethe TrustedAuthentic-ationexamples.
<param name="site_root"value="/t/Sales"/>
<param name="site_root"value=""/>
tabs :tabs yes;no
Displays orhides tabs.
<param name="tabs" value="yes"/>
ticket - num-ber
For trusted <param name="ticket"value="Etdpsm_Ew6rJY-
- 251 -
ObjectPara-meter
URLPara-meter
Val-ues
Descrip-tion
Examples
authen-tication only,cannot beused withthe pathobject para-meter. Mustbe used withname objectto constructthe trustedticketredemptionURL. Seethe TrustedAuthentic-ationexamples.
9kRrALjauU"/>
http://tableauserver/trusted/Etdpsm_Ew6rJY-9kRrALjauU/views/workbookQ4/SalesQ4?:embed=yes&:tabs=yes
tool-bar
:tool-bar
yes;no;top
The toolbaris displayedby defaulton the bot-tomwhenthis para-meter is notset. Whenno the tool-bar isexcludedfrom theembeddedview.Whentop, thetoolbar isplacedabove theview.
<param name="toolbar"value="top"/>
http://tabserver/views/Date-Time/DateCalcs?:embed=yes&:toolbar=no
ExamplesHere are some examples of ways you can customize or work with your embed code:
- 252 -
Add FiltersYou can pass filter values so the view opens showing just the data you want. For example, youmaywant to include a hyperlink from another part of your web application to an embeddedsales performance view that only shows a specific region. If you use the raw URL to specify thevalue of the name parameter or to create your Iframe source, exclude the hash tag (#) andnumber at the end of the URL. For example, use Sales/Sales-Performance notSales/Sales-Performance#1.
Script Tag Example
<script type="text/javascript" src-c="http://myserver/javascripts/api/viz_v1.js"></script><object class="tableauViz" width="800" height="600" style-e="display:none;">
<param name="host_url" value="http://myserver/" /><param name="site_root" value="" /><param name="name" value="Sales/Sales-Performance" /><param name="filter" value="Region=East" />
</object>
To pass throughmultiple filters, just separate each value with a comma. For example:
<param name="filter" value="Region=East,West" />
Iframe Tag Examples
<iframe src-="h-ttp://myserver/views/CalculatedFields?:embed=yes&Region=East"width="800"height="600"></iframe>
<iframe src="http://myserver/views/Sales/Sales-Per-formance?:embed=yes&Region=East,West" width="900px" height-t="700px"></iframe>
- 253 -
Filter on Multiple FieldsYou can pass filters on asmany fields as you want, including fields that are not in the originalview.
Script Tag Example
<script type="text/javascript" src-c="http://myserver/javascripts/api/viz_v1.js"></script><object class="tableauViz" width="800" height="600" style-e="display:none;">
<param name="host_url" value="http://myserver/" /><param name="site_root" value="" /><param name="name" value="Sales/Sales-Performance" /><param name="filter" value="Region=East,West&Customer Seg-
ment=Consumer,HomeOffice" /></object>
Iframe Tag Example
<iframe src-="h-ttp://myserver/views/CalculatedFields?:embed=yes&Region=East,West&CustomerSegment=Consumer,Home Office" width="800" height="600"></iframe>
- 254 -
If a filter value contains a special character, such as a comma, replace the character withthe URL encoding sequence for \ (backslash, %5c) followed by the URL encodingsequence for the special character. The backslash is needed to escape the specialcharacter. For example, the URL encoding sequence for \, (backslash, comma) is%5c%2c. Also, if you use the raw URL to specify the value of the name parameter or tocreate your Iframe source, exclude the hash tag (#) and number at the end of the URL.For example, use Sales/Sales-Performance not Sales/Sales-Performance#1.
Filter Dates and TimesIf you want to filter on a Date/Time field, include the value using the default Tableau formatshown below:yyyy-mm-dd hh:mm:ss
The time part uses a 24-hour clock. Many databases store all date values asDatetime fields, soyoumay need to pass a time value along with your date.
Script Tag Example
<script type="text/javascript" src-c="http://myserver/javascripts/api/viz_v1.js"></script><object class="tableauViz" width="800" height="600" style-e="display:none;">
<param name="host_url" value="http://myserver/" /><param name="site_root" value="" /><param name="name" value="Sales/Sales-Performance" />
- 255 -
<param name="filter" value="Date=2012-12-01" /></object>
This example filters on both a date field and a datetime field:
<param name="filter" value="2012-12-01%2022:18:00" />
Iframe Tag Example
<iframe src="http://myserver/Sales/Sales-Per-formance?:embed=yes&Date=2008-12-01%2022:18:00" width="800"height="600"></iframe>
To filter multiple dates, separate each date with a comma.
If you use the raw URL to specify the value of the name parameter or to create your Iframesource, exclude the hash tag (#) and number at the end of the URL. For example, useSales/Sales-Performance not Sales/Sales-Performance#1.
Filter MeasuresYou can filter measures by including one or more values. There is no support for greater than,less than, or ranges. The example below filters to show only $100 and $200 sales.
Script Tag Example
<script type="text/javascript" src-c="http://myserver/javascripts/api/viz_v1.js"></script><object class="tableauViz" width="800" height="600 "style-e="display:none;">
<param name="host_url" value="http://myserver/" /><param name="site_root" value="" /><param name="name" value="Sales/Sales-Performance" /><param name="filter" value="Profit=100, 200" />
</object>
Iframe Tag Example
<iframe src="http://myserver/Sales/Sales-Per-formance?:embed=yes&Profit=100,200" width="800" height-t="600"></iframe>
If you use the raw URL to specify the value of the name parameter or to create your Iframesource, exclude the hash tag (#) and number at the end of the URL. For example, useSales/Sales-Performance not Sales/Sales-Performance#1.
- 256 -
Control the Load Order of Multiple ViewsYou can control the order in whichmultiple views load for the people working with your views.This feature can only be accessed using embed code that relies on the Tableau JavaScript file.
In the following example, two views are embedded. The second view loads first, followed bythe top view. If you embedmultiple views and give them all the same load order value, or if youdon't specify load order parameters, they are loaded in the order in which they appear on thepage.
Script Tag Example
<script type="text/javascript" src-c="http://myserver/javascripts/api/viz_v1.js"></script><object class="tableauViz" width="600" height="400" style-e="display:none;">
<param name="host_url" value="http://myserver/" /><param name="site_root" value="" /><param name ="name" value="MyCoSales/TopPerformers" /><param name="tabs" value="yes" /><param name="toolbar" value="yes" /><param name="filter" value="Salesperson=Top 5" /><param name="load-order" value="0" />
</object><script type="text/javascript" src-c="http://myserver/javascripts/api/viz_v1.js"></script><object class="tableauViz" width="600" height="400" style-e="display:none;">
<param name="host_url" value="http://myserver/" /><param name="site_root" value="" /><param name="name" value="MyCoSales/SalesScoreCard" /><param name="tabs" value="yes" /><param name="toolbar" value="yes" /><param name="load-order" value="-1" />
</object>
Embed Code for Custom ViewsWhen you embed a view of a workbook or sheet that has custom views available:
l If the embed code URL for the view explicitly refers to a custom view, that custom viewwill be displayed by default.
l If the embed code URL does not explicitly refer to a custom view, and a Default customview has been defined, the Default custom view will be displayed in the embedded viewby default.
- 257 -
l If no Default custom view has been defined, the original view will be displayed in theembedded view by default.
Note: To ensure the original view will be displayed by default in an embedded view,make sure the embed code URL for the name parameter does not explicitly refer to acustom view, and include the following filter parameter in the embed code: <paramname='filter' value=':original_view=yes'/>.
In the following example, the embed code will always display the original view of the ProfitAnalysis sheet in the Profit Analysis workbook, because the filter parameter is set to:original_yes, and the name parameter does not refer to a specific custom view in theURL for the sheet.
<script type='text/javascript' src-c='http://mysite.myserver.com/javascripts/api/viz_v1.js'></script>
<div class='tableauPlaceholder' style='width: 1496px; height:749px;'>
<object class='tableauViz' width='1496' height='749' style-e='display:none;'>
<param name='host_url' value='mysite.myserver.com' /><param name='site_root' value='' /><param name='name' value='ProfitAnalysis/ProfitAnalysis' /><param name='tabs' value='yes' /><param name='toolbar' value='yes' /><param name='filter' value=:original_view=yes' /></ob-
ject></div>
In this example, the setting for the nameparameter in this example specifically refers to theURL for a custom view named Furniture (in the Profit Analysis sheet in the Profit Analysisworkbook).
<script type='text/javascript' src-c='http://mysite.myserver.com/javascripts/api/viz_v1.js'></script>
<div class='tableauPlaceholder' style='width: 1496px; height:749px;'>
<object class='tableauViz' width='1496' height='749' style-e='display:none;'>
<param name='host_url' value='mysite.myserver.com' /><param name='site_root' value='' /><param name='name' value-
e='ProfitAnalysis/ProfitAnalysis/Furniture' /><param name='tabs' value='yes' /><param name='toolbar' value='yes' /></object></div>
- 258 -
In this example, the name parameter does not refer to a specific custom view in the URL for thesheet, and the original_view parameter has not been specified. The embed code here willdisplay the custom view that has been set to Default in the Profit Analysis sheet in the ProfitAnalysis workbook. However, if the original view is still the Default (no other custom view hasbeen set to Default), then the original view will be displayed as the default view.
<script type='text/javascript' src-c='http://mysite.myserver.com/javascripts/api/viz_v1.js'></script>
<div class='tableauPlaceholder' style='width: 1496px; height:749px;'>
<object class='tableauViz' width='1496' height='749' style-e='display:none;'>
<param name='host_url' value='mysite.myserver.com' /><param name='site_root' value='' /><param name='name' value='ProfitAnalysis/ProfitAnalysis' /><param name='tabs' value='yes' /><param name='toolbar' value='yes' /></object></div>
Embed Views into SharePoint (Microsoft SSPI)You can embed a Tableau Server view in a SharePoint page. To automatically authenticateTableau Server users who access the embedded view you have two choices, both of whichdepend on which user authenticationmethod was selected during Tableau Server Setup. Youcan use eitherActive DirectorywithEnable automatic logon to authenticate TableauServer users (also known as usingMicrosoft SSPI), or you can use Local Authentication—and then also configure Tableau Server for trusted authentication.
This topic applies to the first option, where both Tableau Server and SharePoint are usingMicrosoft SSPI. If your Tableau Server is using Local Authentication, seeEmbed Viewsinto SharePoint (Local Authentication) on page 262 for steps.
Requirements
Licensed users: Anyone who accesses an embedded view must be a licensed user onTableau Server.
SharePoint version: To embed Tableau Server views in SharePoint pages, youmust beusing SharePoint 2013. This version of SharePoint usesMicrosoft .NET Framework version4.5, whichmeets Tableau Server's security requirements.
Embedding a View into SharePoint
Follow the steps below to use SharePoint's Page Viewer Web Part embed a view in aSharePoint page.
- 259 -
1. Navigate to the SharePoint page that you want to embed a view into (the page typeshould beWeb Part Page).
2. On the Site Actionsmenu in the upper left corner of the page selectEdit Page.3. ClickAdd a Web Part in the section of the page where you want to embed the view.4. Under Categories, select TableauEmbeddedView located in theMiscellaneous or
Custom folder and clickAdd.
5. Back on the SharePoint page selectEdit Web Part on the Edit menu for the new webpart.
6. On the right side of the page, you can specify the attributes of the Page ViewWeb Part.Type the URL for the view you want to embed, excluding the hash tag (#) and numberthat appear at the very end of the URL. Use the format specified inEmbed Views intoWebpages on page 244. For example youmay type:
http://tableauserver/views/Date-Time/DateCalc-s?:embed=yes&:toolbar=no
- 260 -
7. In the Appearance section you can specify a Title of the web part, theHeight, andWidth. In general you should specify a fixed height (e.g., 700 Pixels) and adjust thewidth to fit to the zone.
8. ClickOK to apply the changes and exit edit mode.
The view will be embedded into the web part that you just created. Your users will notneed to log in to Tableau Server to see the embedded view, rather theywill beautomatically authenticated usingMicrosoft SSPI.
- 261 -
Embed Views into WikisYou can easily embed a view into a wiki or other web page simply by putting the view inside an<iframe> tag.
1. Navigate to the wiki page you want to embed a view into.
2. Edit the page and add an <iframe> where the source is the URL for the view,excluding the hash tag (#) and number at the end. For example:
<iframe src="http://tableauserver/views/Date-Time/DateCalc-s?:embed=yes&:toolbar=no" width="800" height="600"></iframe>
3. Save your changes.
The view is embedded into the wiki page.
If both Tableau Server and the wiki are configured to useMicrosoft SSPI, usersaccessing an embedded view on the wiki will be automatically signed in so they can seethe view.
If the server and the wiki are not using the samemethod for authentication, users will firstbe asked to sign in to the server before they can see the view.
Embed ImagesIn addition to embedding a view into a <script> or <iframe> tag you can also embed theview as an image.When you embed an image the view is not interactive, however, it is updatedevery time the page fully reloads. That way the image shows the latest data even if theunderlying data changes.
1. Navigate to the page where you want to embed the image.
2. Edit the page and add an <img> tag where the source is the URL for the view plus the.png file extension (but excluding the hash tag and number). For example:
- 262 -
<img src="http://tableauserver/views/Date-Time/DateCalcs.png"width="900" height="700">
Note:Due to a temporary product limitation, the above apporach will only work if the user accessingthe embedded image also has an active web browser session with Tableau Server, and issigned in to Tableau Server usingMicrosoft SSPI.
Embed Views into SharePoint (Local Authentication)You can embed a Tableau Server view in a SharePoint page. If Local Authentication isTableau Server's user authenticationmethod, there are some extra steps you need to takebefore you start embedding views. The steps identify Tableau Server users, among otherthings, to SharePoint. Tableau provides this functionality through the supplemental filesTableauEmbeddedView.dll and TableauEmbeddedView.wsp. This topic describes how toinstall and provision these files, test your configuration, then embed a view using a SharePointWeb Part. If Active Directory is your user authenticationmethod, you do not need to take theseextra steps—because both Active Directory and SharePoint useMicrosoft SSPI. You can startembedding right away. SeeEmbed Views into SharePoint (Microsoft SSPI) on page 258for steps.
Requirements
Licensed users and matching usernames: Anyone who accesses an embedded viewmust be a licensed user on Tableau Server and their user name on SharePoint must be thesame as their user name on Tableau Server.
SharePoint version: To embed Tableau Server views in SharePoint pages, youmust beusing SharePoint 2013. This version of SharePoint usesMicrosoft .NET Framework version4.5, whichmeets Tableau Server's security requirements.
Edit Security Permissions for the DLL
The first step is to edit the security permissions of the .dll so that all users of the operatingsystem can use it.
1. Locate the TableauEmbeddedView.dll and TableauEmbeddedView.wsp files that installwith Tableau Server:C:\Program Files\Tableau\TableauServer\8.2\extras\embedding\sharepoint\
2. Copy the files to the root directory of your SharePoint server. The root directory isusually located atC:\Inetpub\wwwroot\wss\VirtualDirectories\<port>\bin, forexample:
C:\Inetpub\wwwroot\wss\VirtualDirectories\80\bin
- 263 -
The rest of this procedure and all of the next will focus on just the .dll file.
3. Edit the security permissions on TableauEmbeddedView.dll by right-clicking it andselectingProperties > Security.
4. UnderGroup or user names, select Everyone, then clickEdit.
5. Under Permissions for Everyone, selectAllow for the Full control permission.
- 264 -
6. ClickOK.
Install and Deploy the WSP File
The above procedure granted all operating system users permission to use the .dll file. In thefollowing procedure you will give SharePoint more information about what to do with the .dllfile. This is handled by the TableauEmbeddedView.wsp file. You copied this file as part of step2 inEdit Security Permissions for the DLL on page 262. To install and deploy the .wsp file:
1. Open a command prompt as an administrator.
2. Navigate to the following folder:
C:\Program Files (x86)\Common Files\Microsoft Shared\WebServer Extensions\14\BIN
3. Run the following command to add the .wsp file:stsadm -o addsolution -filename"C:\Inetpub\wwwroot\wss\VirtualDirectories\80\bin\TableauEmbeddedView.wsp"
4. Next, run the following command to deploy it. In the command, http://<your
- 265 -
SharePoint site>/ should be the root directory of your SharePoint site, such ashttp://mySharePoint/.
stsadm -o deploysolution -name TableauEmbeddedView.wsp -urlhttp://<your SharePoint Site>/ -local -force -allowgacde-ployment
5. Finally, activate theWeb Part feature by running the following command:
stsadm -o activatefeature -name TableauEmbeddedView_Feature1-url http://<your SharePoint Site>/
Verify the Web Part's Deployment
After you install and deploy the TableauEmbeddedView.wsp file, verify your settings by doingthe following:
1. Open your SharePoint site in a web browser. It may take a few moments for the site toappear.
2. From theSite Actions list selectSite Settings.3. UnderGalleries, selectWeb parts.
4. Confirm that TableauEmbeddedView is listed.
- 266 -
5. Return toSite Settings and under Site Collection Administration, selectSitecollection features.Confirm that the TableauEmbeddedView Feature has a status ofActive.
Embed a View Using the Web Part
Now you are ready to embed a view in a SharePoint page:
1. Navigate to the SharePoint page that you want to embed a view into (the page typeshould beWeb Part Page).
2. On the Site Actionsmenu in the upper left corner of the page selectEdit Page.3. ClickAdd a Web Part in the section of the page where you want to embed the view.4. Under Categories, select TableauEmbeddedView located in theMiscellaneous or
Custom folder and clickAdd.
5. Back on the SharePoint page selectEdit Web Part on the Edit menu for the new webpart.
- 267 -
6. On the right side of the page, you can specify the attributes of theTableauEmbeddedView web part. Type the name of your Tableau Server, then type thepath to the view you want to embed. For example youmay type /views/Date-Time/DateCalcs (exclude the hash tag (#) and number at the very end of the URL).
7. Specify other attributes such aswhether you want to show the toolbar, or even if youwant embed the view as an image instead of as an interactive view.
8. In theAppearance section you can specify a Title of the web part, theHeight, andWidth. In general you should specify a fixed height (e.g., 700 Pixels) and adjust thewidth to fit to the zone.
- 268 -
9. ClickOK to apply the changes and exit edit mode.
Now the view is embedded in the page and users who access it will be automaticallysigned in based on their user name and password for SharePoint. Anyone whoaccesses an embedded view needs to be a licensed user on Tableau Server and theiruser name on SharePoint must be the same as their user name on Tableau Server.
This is an example of embedding views into SharePoint using the provided .dll file.You can also embed views into other types of web applications. See JavaScriptAPI on page 396 for more information.
- 269 -
Proxy ServersTableau Server can be configured to work with a proxy server. In this type of environment, theproxy server acts as an intermediary between Tableau Server and the clients that aremakingrequests for resources on Tableau Server. There are several ways to configure proxyservers—for example, as forward proxies or reverse proxies. These topics assume that youhave already configured your proxy server, and now need to identify your proxy server toTableau Server.
Use the topics below for more information:
Prepare to Configure for a Proxy EnvironmentTo configure Tableau Server to work with a proxy server, you will need the followinginformation about your proxy server:
l IP address: The IP address of the proxy server. The IP addressmust be in IPv4 format,for example, 123.45.67.890, and it must be a static IP.
l FQDN: The fully-qualified domain name of the proxy server. For example,bigbox.myco.com.
l Non-FQDN: Any non-fully-qualified domain names for the proxy server. Using theabove example, the non-fully-qualified domain name of the proxy server would bebigbox.
l Aliases: Any aliases for the proxy server. Aliases are designated using CNAMEs(Canonical Name records). An example would be a proxy server with a CNAME ofbigbox.myco.com and aliases of ftp.myco.com andwww.myco.com.
Apache reverse proxy servers are not supported if Tableau Server is using SSPI (ActiveDirectory with Enable automatic logon) for authenticating Tableau Server users. Apachereverse proxy servers are supported if Tableau Server is authenticating server userswith just Active Directory (noEnable automatic logon), Local authentication, orSAML.
Configure Tableau to Work with a Proxy ServerAfter you collect the information described inPrepare to Configure for a ProxyEnvironment above, you can configure Tableau Server to work with a proxy by performingthe following steps. For information on the settings below, see tabadmin set options on page358.
1. Stop the server.
2. Still in the Tableau Server bin directory, enter the following command, where name isthe URL that will be used to reach Tableau Server through the proxy server:
- 270 -
tabadmin set gateway.public.host "name"
For example, if Tableau Server is reached by entering tableau.example.com in abrowser address bar, enter this command:tabadmin set gateway.public.host "tableau.example.com"
3. By default, Tableau assumes that the proxy server is listening on port 80 for externalcommunications. To designate a different port, enter the following command, whereport_number is the port:tabadmin set gateway.public.port "port_number"
4. Now, enter the following command, where server_ip_address is the IPv4 addressof the proxy server:tabadmin set gateway.trusted "server_ip_address"
The value for server can be a comma-separated list, for example:tabadmin set gateway.trusted "123.45.67.890, 123.45.67.880,123.45.67.870"
5. In the next command, you will provide any alternate names for the proxy server, such asits fully-qualified domain name, any non-fully-qualified domain names, and any aliases.These are the names a user might type in a browser. Separate each namewith acomma:tabadmin set gateway.trusted_hosts "name1, name2, name3"
For example:tabadmin set gateway.trusted_hosts "proxy1.example.com,proxy1, ftp.example.com, www.example.com"
6. Start the server so the changes can take effect.
- 271 -
Trusted AuthenticationWhen you embed Tableau Server views into webpages, everyone who visits the pagemust bea licensed user on Tableau Server. When users visit the page they are prompted to sign in toTableau Server before they can see the view. If you already have a way of authenticating userson the webpage or within your web application, you can avoid this prompt and save your usersfrom having to sign in twice by setting up trusted authentication.
Trusted authentication simplymeans that you have set up a trusted relationship betweenTableau Server and one or more web servers. When Tableau Server receives requests fromthese trusted web servers it assumes that your web server has handled whateverauthentication is necessary.
If your web server uses SSPI (Security Support Provider Interface), you do not need to set uptrusted authentication. You can embed views and your users will have secure access to themas long as they are licensed Tableau Server users andmembers of your Active Directory.Using both Enable automatic login (an option configured during Setup that usesMicrosoftSSPI) and trusted authentication is not supported. If you are not using SSPI with ActiveDirectory and you want your users to have secure access to Tableau Server viewswithoutbeing prompted for credentials, you can set up trusted authentication.
So that users can be authenticated when they click an embedded view, their browsersmust be configured to allow third-party cookies.
How Trusted Authentication WorksThe diagram below describes how trusted authentication works between the client's webbrowser, your web server(s) and Tableau Server.
- 272 -
User visits the webpage:When a user visits thewebpage with the embeddedTableau Server view, it sendsaGET request to your webserver for the HTML for thatpage.
Web server passes the URL to the browser:The web server constructs the URL for the viewusing either the view’s URL or its object tag (if theview’s embedded), and inserts it into the HTML forthe page. The ticket is included (e.g.,http://tabserver/trusted/<ticket>/views/requestedviewname). The web server passes all the HTML forthe page back to the client’s web browser.
Web server POSTS toTableau Server: The webserver sends a POST requestto the trusted Tableau Server(for example,http://tabaserver/trusted, nothttp://tabserver). ThatPOST request must have ausername parameter. Theusername valuemust be theusername for a licensedTableau Server user. If theserver is runningmultiple sitesand the view is on a site otherthan the Default site, thePOST request must alsoinclude a target_siteparameter.
Browser requests view from Tableau Server:The client web browser sends a request to TableauServer using aGET request that includes the URLwith the ticket.
Tableau Server creates aticket: Tableau Server checksthe IP address or host name ofthe web server(192.168.1.XXX in the abovediagram) that sent the POSTrequest. If it is set up as atrusted host then TableauServer creates a ticket in theform of a unique 24-character(URL-safe, Base64-encoded)string. Tableau Serverresponds to the POST requestwith that ticket. If there is anerror and the ticket cannot becreated Tableau Serverrespondswith a value of -1.
Tableau Server redeems the ticket: TableauServer sees that the web browser requested a URLwith a ticket in it and redeems the ticket. Ticketsmust be redeemedwithin threeminutes after theyare issued. Once the ticket is redeemed, TableauServer logs the user in, removes the ticket from theURL, and sends back the final URL for theembedded view.
- 273 -
Add Trusted IP Addresses or Host Names to Tableau ServerThe first step in setting up trusted authentication is to configure Tableau Server to recognizeand trust requests from one or more web servers:
1. Open a command prompt as an administrator and navigate to your Tableau Server bindirectory (for example, C:\ProgramFiles\Tableau\Tableau Server\8.2\bin).
2. Type the following command to stop Tableau Server:
tabadmin stop
3. Next, type the following command:
tabadmin set wgserver.trusted_hosts "<trusted IP addresses orhost names>"
In the command above, <trusted IP addresses> should be a comma-separatedlist of the IPv4 addresses or host names of your web server(s). For example:
tabadmin set wgserver.trusted_hosts "192.168.1.101,192.168.1.102, 192.168.1.103"
or
tabadmin set wgserver.trusted_hosts "webserv1, webserv2, web-serv3"
Notes:The comma separated list should be in quotes, with one space after each comma.The web servers you specifymust use static IP addresses, even if you use hostnames here (learnmore).
4. If you have one or more proxy servers between the computer that is requesting thetrusted ticket (one of those configured in step 2, above) and Tableau Server, you alsoneed to add them as trusted gateways. SeeConfigure Tableau to Work with aProxy Server on page 269 for steps.
5. Type the following command to save the changes to all the server configuration files:
tabadmin config
6. Finally, type the following command to start the server again:
tabadmin start
Next, you need to configure your web server to receive tickets from Tableau Server.
- 274 -
Get a Ticket from Tableau ServerAfter you’ve added trusted IP addresses to Tableau Server, you’re ready to configure your webserver to get tickets from Tableau Server via POST requests (step 3 in the diagram). ThePOST request must be sent to http://<server name>/trusted, nothttp://tabserv. For example http://tabserv/trusted.
Note: If SSL is enabled youmust use https instead of http. Forexample: https://tabserver/trusted.
For code examples that you can use to create the POST request in Java, Ruby, and PHP, seethe following:
C:\Program Files\Tableau\Tableau Server\8.2\extras\embedding
Here’s the data you can use in a POST request to Tableau Server:
l username=<username> (required): The username for a licensed Tableau Serveruser. If you are using Local Authentication the username can be a simple string (forexample, username=jsmith). If you are using Active Directory with multiple domainsyoumust include the domain namewith the user name (for example,username=MyCo\jsmith).
l target_site=<site id> (required if view not on Default site): Specifies the sitecontaining the view if Tableau Server is runningmultiple sites and the view is on a siteother than the Default site (for example, target_site=Sales). The value you use for<site id> should be the Site ID that was provided when the site was created. Thisvalue is case sensitive. If theSite ID is SAles, then the target_site=SAles.
l client_ip=<IP address> (optional): Used to specifiy the IP address of thecomputer whose web browser is accessing the view (for example, client_ip=123.45.67.891). It is not the IP address of the web server making the POSTrequest of Tableau Server. If you decide to use this parameter, seeOptional:Configure Client IP Matching on page 276 for more information.
Tableau Server’s response to the POST request will be a unique 24-character string (theticket). If Tableau Server isn’t able to process the request, the return will be -1. See TicketValue of -1 Returned from Tableau Server on page 277 for tips on how to correct this. Also,in order for users to successfully authenticate when they click an embedded view, theirbrowsersmust be configured to allow third-party cookies.
Next, you need to add code that allows the web server to construct an URL for the view thatincludes the view’s location and the ticket.
Display the View with the TicketAfter you create the POST request, you need to write code that provides the web server withthe view’s location and the ticket from Tableau Server. It will use this information to display the
- 275 -
view. How you specify it depends on whether the view is embedded, and if Tableau Server isrunningmultiple sites.
Tableau Server View ExamplesHere’s an example of how to specify a view that users only access via Tableau Server (theview is not embedded):
http://tabserver/trusted/<ticket>/views/<workbook>/<view>
If Tableau Server is runningmultiple sites and the view is on a site other than the Default site,you need to add t/<site ID> to the path. For example:
http://tabserver/trusted/<ticket>/t/Sales/views/<workbook>/<view>
Use the same capitalization that you see in the Tableau Server URL.
Embedded View ExamplesHere are some examples of how to specify embedded views. Because there are twoapproaches you can take with embed code, both ways are provided below. Regardless ofwhich you use, there is some information unique to trusted authentication that youmustprovide.
Script Tag ExamplesThis example uses the ticket object parameter:
<script type="text/javascript" src-c="http://myserver/javascripts/api/viz_v1.js"></script><object class="tableauViz" width="800" height="600" style-e="display:none;">
<param name="name" value="MyCoSales/SalesScoreCard" /><param name="ticket" value="Etdpsm_Ew6rJY-9kRrALjauU" />
</object>
Here’s what the above example looks like for amulti-site Tableau Server, where the view ispublished on the Sales site:
<script type="text/javascript" src-c="http://myserver/javascripts/api/viz_v1.js"></script><object class="tableauViz" width="800" height="600" style-e="display:none;">
<param name="site_root" value="/t/Sales" /><param name="name" value="MyCoSales/SalesScoreCard" /><param name="ticket" value="Etdpsm_Ew6rJY-9kRrALjauU" />
</object>
- 276 -
Instead of using ticket, you can use the path parameter to state the full path of the viewexplicitly. When path is used, you do not also need the name parameter, which is usually arequired parameter in Tableau JavaScript embed code:
<script type="text/javascript" src-c="http://myserver/javascripts/api/viz_v1.js"></script><object class="tableauViz" width="900" height="700" style-e="display:none;">
<param name="path" value="trusted/Etdpsm_Ew6rJY-9kRrAL-jauU/views/MyCoSales/SalesScoreCard" /></object>
Here’s the same example, but for amulti-site server. Note that /t/<site ID> is used here:
<script type="text/javascript" src-c="http://myserver/javascripts/api/viz_v1.js"></script><object class="tableauViz" width="900" height="700" style-e="display:none;">
<param name="path" value="trusted/Etdpsm_Ew6rJY-9kRrAL-jauU/t/Sales/views/MyCoSales/SalesScoreCard" /></object>
Iframe Tag Example
<iframe src="http://tabserver/trusted/Etdpsm_Ew6rJY-9kRrAL-jauU/views/workbookQ4/SalesQ4?:embed=yes" width="800" height-t="600"></iframe>
Optional: Configure Client IP MatchingBy default, Tableau Server does not consider the client web browser IP addresswhen itcreates or redeems tickets. To change this, you need to do two things: specify an IP addressusing the client_ip parameter in the POST request that obtains the ticket, and follow thesteps below to configure Tableau Server to enforce client IP addressmatching.
1. Open a commandwindow and change directories to the location of Tableau Server's bindirectory. The default location is C:\Program Files\Tableau\TableauServer\8.2\bin
2. Open a command prompt as an administrator and type the following command:
tabadmin set wgserver.extended_trusted_ip_checking true
3. Then type the following command:
tabadmin configure
- 277 -
4. Finally, restart the server by typing the following:
tabadmin restart
Troubleshoot Trusted AuthenticationBelow are some common issues and errors youmight encounter when you're configuringtrusted authentication. Trusted authentication information is written toProgramData\Tableau\TableauServer\data\tabsvc\logs\vizqlserver\vizql-*.log. To increase the logginglevel from info to debug, use the tabadmin setting vizqlserver.trustedticket.log_level.
For tips on testing trusted authentication, see the Tableau Knowledge Base.
Ticket Value of -1 Returned from Tableau ServerTableau Server returns -1 for the ticket value if it cannot issue the ticket as part of the trustedauthentication process. The exact reason for thismessage is written to the fileproduction*.log in the following folder:
ProgramData\Tableau\Tableau Server\data\tabsvc\logs\wgserver
and to the vizql*.log in the following folder:
ProgramData\Tableau\Tableau Server\data\tabsvc\logs\vizqlserver
Here are some things to confirm:
l All web server host names or IP addresses are added to trusted hostsThe IP address or host name for the computer sending the POST request must be in thelist of trusted hosts on Tableau Server. SeeAdd Trusted IP Addresses or HostNames to Tableau Server on page 273 to learn how to add IP addresses or hostnames to this list.
l Value of wgserver.trusted_hosts is properly formattedThe list of trusted hosts you provided using the wgserver.trusted_hosts settingmust be acomma-separated list with a space after each comma. For example, the list should besimilar to the following: 192.168.1.101, 192.168.1.102, 192.168.1.103, orbigbox1.example.lan, bixbox2.example.lan, bigbox3.example.lan.
l IP addresses are IPv4If you are using IP addresses to specify trusted hosts, theymust be in Internet Protocolversion 4 (IPv4) format. An IPv4 address looks like this: 123.456.7.890. IPv6 addresses(for example, fe12::3c4a:5eab:6789:01c%34) are not supported as a way of inputtingtrusted hosts.
l Username in POST request is a valid Tableau Server user
- 278 -
The username you send in the POST request must be a licensed Tableau Server userwith a Viewer or Interactor license level. You can see a list of users and their licenselevels by signing in to Tableau Server as an administrator and clicking the Licensing linkon the left side of the page.
l Username in POST request includes domainIf Tableau Server is configured to use Local Authentication, the username that you sendin the POST can be a simple string. However, if the server is configured for ActiveDirectory youmust include the domain namewith the user name (domain\username).For example, the username parameter might be: username=dev\jsmith
l Content-Type is specifiedIf you are designing an ASP.NET or C# application, you need to declare the content typein your HTTP request. For example, http.setRequestHeader("Content-Type","application/x-www-form-urlencoded;charset=UTF-8"). If youdo not specify content type and Tableau Server returns a -1, the log files contain theerror: "missing username and/or client_ip".
HTTP 401 - Not AuthorizedIf you receive a 401- Not Authorized error, youmay have configured Tableau Server to useActive Directory with SSPI (see Enable automatic login). If your web server uses SSPI, you donot need to set up trusted authentication. You can embed views and your users will haveaccess to them as long as they are licensed Tableau server users andmembers of your ActiveDirectory.
Concurrent use of Enable automatic login and trusted authentication is not supported.
HTTP 404 - File Not FoundYoumay receive this error if your program code references a Tableau Server URL that doesnot exist. For example, your web server may construct an invalid URL that cannot be foundwhen the webpage tries to retrieve it.
Invalid User (SharePoint or C#)Youmay encounter this error if you’ve configured Tableau Server for trusted authentication.
The example code for the SharePoint .dll references the followingGET request:
SPContext.Current.Web.CurrentUser.Name
The above request will return the display name of the currentWindowsActive Directory user. Ifyou want to use the login ID, then you will need to change the code to:
SPContext.Current.Web.CurrentUser.LoginName
After youmake the change, recompile the SharePoint .dll.
- 279 -
Attempting to Retrieve the Ticket from the Wrong IP AddressYoumay encounter this error if you’ve configured Tableau Server for trusted authentication.
The client web browser IP address is not considered by default when redeeming the ticket. IfTableau Server is configured to enforce client IP addressmatching, make sure that the client'sweb browser IP address that is sent in the POST to Tableau Server is the same aswhen thebrowser tries to retrieve the embedded view. For example, in the Trusted Authenticationdiagram, if the POST request in step 3 sends the parameter client_ip=74.125.19.147, then theGET request in step 5must come from that same IP address.
SeeOptional: Configure Client IP Matching on page 276 to learn how to configureTableau Server to enforce client IP addressmatching.
Cookie Restriction ErrorWhen a user signs in to Tableau Server, a session cookie is stored in their local browser. Thestored cookie is how Tableau Server maintains that the signed in user has been authenticatedand can access the server. Because the cookie is set with the same domain or sub-domain asthe browser's address bar, it is considered a first-party cookie. If a user's browser is configuredto block first-party cookies, theywill be unable to sign in to Tableau Server.
When a user signs in to Tableau Server via an embedded view, or in an environment wheretrusted authentication has been configured, the same thing happens: a cookie is stored. In thiscase, however, the browser treats the cookie as a third-party cookie. This is because thecookie is set with a domain that's different from the one shown in the browser's address bar. Ifa user's web browser is set to block third-party cookies, authentication to Tableau Server willfail. To prevent this from occurring, web browsersmust be configured to allow third-partycookies.
An error occurred communicating with the server (403)If Tableau Server is configured for trusted authentication, youmay receive this error afteropening a new view in a browser and attempting to navigate back to views you'd openedearlier. Tableau Server provides protection against unauthorized reuse of VizQL sessionsthrough the tabadmin set option vizqlserver.protect_sessions, which is set to true by default.Because Tableau Server is configured for trusted authentication, youmay not also need toenable vizqlserver.protect_sessions. To disable it, use set on page 353 to change itto false.
- 280 -
Protect Credentials for Cloud DataFor some cloud-based data sources, an alternative to storing sensitive database credentials inTableau Server is to establish a limited-purpose trust relationship between Tableau and thedata-source provider. Through this relationship, you can access your data while keeping yourcredentials secure with the data-source provider.
To establish this type of relationship, you authorize Tableau to access your cloud data. Thecloud data provider then sends Tableau a limited-purpose access token, which uniquelyidentifies requests from Tableau and allows Tableau to access the data on your behalf.
Tableau workswith these protected connections as specified in theOAuth 2.0 open-authorization standard. Using OAuth connections provides the following benefits:
l Security: Your sensitive database credentials are never known to or stored in TableauServer, and the access token can be used only by Tableau.
l Convenience: Instead of having to embed your data source ID and password inmultiple places, you can use the token provided for a particular data provider for allpublished workbooks and data sources that access that data provider.
In addition, for live connections to Google BigQuery data, each workbook viewer canhave a unique access token that identifies the user, rather than sharing a single username and password credential.
Protected authentication is available for Google BigQuery, Google Analytics, andSalesforce.com data sources.
Overview of the OAuth ProcessThe following steps describe a workflow in the Tableau environment that calls the OAuthprocess.
1. You take an action that requires access to a cloud data source.
For example, you open a workbook that’s published to Tableau Server.
2. Tableau directs you to the hosted data provider’s sign-in page. The information that issent to the hosted data provider identifies Tableau as the requesting site.
3. When you sign in to the hosted data source, it prompts you to confirm your authorizationfor Tableau Server access to the data.
4. Upon your confirmation, the data-source provider sends an access token back toTableau Server.
- 281 -
5. Tableau Server presents your workbook and data to you.
The following are other workflows that can use theOAuth process:
l Creating a workbook and connecting to the data source from Tableau Desktop or fromTableau Server.
l Publishing a data source from Tableau Desktop.
Managing CredentialsUsers canmanage their own access tokens in user preferences, or you can choose to allowonly administrators and users with the Data Source Connector role tomanage access tokensacross data sources and connections.
The following applies whether an access token is used as an embedded credential with apublished data source or used for live connections to Google BigQuery data:
l When Tableau Server requests data through a connection represented by an accesstoken, the data-source provider confirms authorized Tableau access through the token,and then returns the requested data. You do not need to provide credentials each timeyou connect.
l If the token is used as an embedded credential with a published data source, you cancreate new workbooks that connect to that data from Tableau Desktop or TableauServer, without having to sign in each time to access the data.
l Access tokens are valid until a user or data provider revokes them.
Note It is possible to exceed the number of access tokens a data source providerallows. If that's the case, when a new token is created, the data provider uses
- 282 -
length of time since last access to decide which token to invalidate tomake roomfor the new one. The data provider can also invalidate a token for other reasons.For example, an administrator might revoke all application access.
Configure the Server for OAuth SupportInstead of individual usernames and passwords, OAuth works through limited-purpose accesstokens. Before you can obtain access tokens needed to create anOAuth connection inTableau, you need to configure your server so that the data provider sending the token canrecognize Tableau Server as a trusted destination. The following section describes how toprepare for setting upOAuth regardless of your data provider. The topics listed below it containthe steps for configuring your server for specific data providers.
Preparing for Configuring OAuth SupportBefore you begin the configuration steps specific to your data provider, complete the followingprerequisites:
l Obtain the fully qualified domain name of each Tableau Server node that will host viewsthat connect to this data source. For example:https://sales.your_domain.com
If you use Salesforce.com, you will need to provide an https address.
l Make sure at least one of your data-provider accounts is enabled for API access.
ForGoogle BigQuery andGoogle Analytics, you need access to the developersconsole on theGoogle Cloud Platform.
For Salesforce.com, you need access to the Force.com platform.
l Make sure you have the latest drivers for the data source.
For Google BigQuery, use the 32-bit version.
You can download updated drivers from the Drivers & Activation page on the Tableauwebsite.
Configure Settings for Your Data ProviderWhen you complete the OAuth-preparation steps, you can configure the appropriate settingswith your data provider.
l Set up OAuth for Google on the next pagel Set up OAuth for Salesforce.com on page 286
- 283 -
Set up OAuth for GoogleThis topic describes how to set up your Google BigQuery andGoogle Analytics data sourcesfor OAuth. Complete these steps for each Tableau Server instance.
NoteBefore you complete these steps, make sure you have completed theprerequisites described inPreparing for Configuring OAuth Support on theprevious page.
Set upOAuth by following these two procedures:
l Get required information fromGoogle and enable API access.l Use the information you obtained to configure your server.
Obtain a Client ID and Enable Google APIs
Note These steps reflect the settings in the Google Cloud Platform console at the time ofthis writing. For more information, see UsingOAuth 2.0 for Web Server Applications inthe Google Developers Console Help.
1. Sign in to Google Cloud Platform, and then clickGo to my console.
2. SelectProjects, and on the Project page, clickCreate Project.
3. In the new project form that appears, complete the following:
l Give the project ameaningful name that reflects the Tableau Server instance forwhich you’ll use this project.
l Determine whether you want to change the project ID.
- 284 -
Note After you create the project, you will not be able to change the projectID. For information, click the questionmark icons.
4. Open the new project, and navigate toAPIs & auth > Credentials.5. ClickCreate a New Client ID, and in the Create Client ID page, complete the following:
l SelectWeb Application.l For Authorized JavaScript Origins, type the local computer name of your TableauServer.
l For Authorized Redirect URI, replace the existing text with the Internet addressfor your server, and add the following text to the end of it: auth/add_oauth_token. For example:https://data.your_server.com/auth/add_oauth_token
6. ClickCreate Client ID.7. Copy the following values that Google returns, and paste them in a location that you can
access from your Tableau Server computer:
l Client ID
l Client secret
l Redirect URIs
8. In the Google Developer Console, with your new project open, selectAPIs & auth> APIs, and then set the status toOn forBigQuery API orAnalytics API.
- 285 -
Configure Tableau Server for Google OAuthUsing the information you obtained by completing the steps inObtain a Client ID and EnableGoogle APIs on page 283, configure your Tableau Server:
1. On the Tableau Server computer, open the Command Prompt as an administrator andchange to the Tableau Server bin directory.cd C:\Program Files\Tableau\Tableau Server\<version>\bin
2. Type the following command to stop the server:tabadmin stop
3. Type the following commands to configure the server with the client ID and client secretyou obtained fromGoogle, as well as your server URI. PressEnter after eachcommand.tabadmin set oauth.google.client_id <your_client_ID>
tabadmin set oauth.google.client_secret <your_client_secret>
tabadmin set oauth.google.redirect_uri <your_server_URI>
4. Type the following commands to complete the configuration and restart the server:tabadmin config
tabadmin start
Allow Users to Save Access Tokens
Instead of individual user names and passwords, OAuth connections aremade through accesstokens.
Server administrators can use the Admin interface (A) to allow users tomanage their ownaccess tokens on their User Preferences page (B).
- 286 -
To enable these settings:
1. Open a web browser and sign in to the server.
2. On the Admin tab, display theMaintenance page, and in the Settings section, select thefollowing:
l Save Passwords to allow users to save their individual credentials with datasources.
l Save Access Tokens to allow users to saveOAuth tokens.
Alternatively, server administrators canmanageOAuth credentials centrally by clearing thesecheck boxes, and editing data connections as data sources are published.When the settingsfor saving passwords and access tokens are not enabled, theManage Credentials section isexcluded from the User Preferences page.
Set up OAuth for Salesforce.comThis topic describes how to set up your Salesforce.com data sources for OAuth. Completethese steps for each Tableau Server instance.
Note: Before you complete these steps, make sure you have completed theprerequisites described inPreparing for Configuring OAuth Support on page 282.
Set upOAuth by following these two procedures:
l Create a Connected App in Salesforcel Use the information you obtained to configure your server.
Create a Connected Salesforce App
1. Sign in to your Salesforce.com developer account, click your user name in the upper-right, and then selectSetup.
2. In the left navigation column, under App Setup, selectCreate > Apps.
- 287 -
3. In the Connected Apps section, clickNew.
4. Complete theBasic Information, and in the API section, selectEnable OAuthSettings.
5. In the new OAuth settings that appear, forCallback URL, type the fully qualified domainname of your server, using the https protocol, and append the following text to the URL:auth/add_oauth_token.For example:https://www.your_server.com/auth/add_oauth_token
6. Move the following items fromAvailable OAuth Scopes to SelectedOAuth Scopes:
l Access and manage your data (api)l Access your basic information (id)l Perform requests on your behalf at any time (refresh_token)
7. ClickSave.
After you save the app, Salesforce populates the API section with the following IDs that you willuse to configure Tableau Server:
l Consumer Keyl Consumer Secretl CallbackURL
- 288 -
Configure Tableau Server for Salesforce.com OAuth
1. On the Tableau Server computer, open the Command Prompt as an administrator andchange to the Tableau Server bin directory:cd C:\Program Files\Tableau\Tableau Server\<version>\bin
2. Type the following command to stop the server:tabadmin stop
3. Type the following commands to configure the server with the consumer ID and secretyou obtained fromSalesforce and the callbackURL. PressEnter after each command:tabadmin set oauth.salesforce.client_id <your_consumer_ID>
tabadmin set oauth.salesforce.client_secret <your_consumer_secret>
tabadmin set oauth.salesforce.redirect_uri <your_callback_URL_>
4. (Optional) To change the default login server, type the following command:tabadmin set oauth.salesforce.server_base_url <URL>
By default, this is set to https://login.salesforce.com.
5. Type the following commands to complete the configuration and restart the server:tabadmin config
tabadmin start
Allow Users to Save Access Tokens
Instead of individual user names and passwords, OAuth connections aremade through accesstokens.
Server administrators can use the Admin interface (A) to allow users tomanage their ownaccess tokens on their User Preferences page (B).
- 289 -
To enable these settings:
1. Open a web browser and sign in to the server.
2. On the Admin tab, display theMaintenance page, and in the Settings section, select thefollowing:
l Save Passwords to allow users to save their individual credentials with datasources.
l Save Access Tokens to allow users to saveOAuth tokens.
Alternatively, server administrators canmanageOAuth credentials centrally by clearing thesecheck boxes, and editing data connections as data sources are published.When the settingsfor saving passwords and access tokens are not enabled, theManage Credentials section isexcluded from the User Preferences page.
- 290 -
SAMLSAML (Security AssertionMarkup Language) is an XML standard that allows secure webdomains to exchange user authentication and authorization data. You can configure TableauServer to use an external identity provider (IdP) to authenticate Tableau Server users overSAML 2.0. All user authentication is done outside of Tableau, regardless of whether you'reusing Active Directory or local authentication in Tableau Server to manage your user accountson Tableau Server. This allows you to provide a single sign-on experience for your usersacross all the applications in your organization.
The SAML support in Tableau Server is for user authentication. It does not handle permissionsand authorization having to do with Tableau Server content, such asworkbooks.
Note: The IdP-provided authentication is a single-use, limited time token.
See the links below for more information about SAML:
How SAML Authentication WorksSAML is an XML-based open standard for exchanging authentication information between twoparties, a service provider (in this case, Tableau Server) and an identity provider (IdP). Whenyou configure Tableau Server for SAML, a third-party IdP is used to authenticate users and topass identity information to Tableau Server in the form of a digitally-signed XML document.Only service provider-initiated authentication will work. Thismeans that users accessingTableaumust access it using the Tableau Server URL, which initiates the authentication, notan IdP URL.
User attempts to access a TableauServer workbook link or otherresource.
IdP sends a SAML success responseto Tableau Server.
Tableau Server starts the authen-tication process and redirects theuser to the IdP.
User opensworkbook on TableauServer.
- 291 -
IdP authenticates the user.
Tableau Server user account. This user-namemust match what the IdP hasstored as the username.
User account on the IdP.
SAML RequirementsTo configure Tableau Server for SAML, you need the following:
Certificate file: A PEM-encoded x509 certificate with the file extension .crt.This file is used byTableau Server, not the IdP. If you have an SSL certificate, you can use the same certificatewith SAML. See About the Certificate File for details.
Certificate key file: An RSA or DSA private key file that is not password protected, and whichhas the file extension .key. This file is used by Tableau Server, not the IdP. The certificate keyfile must have the passphrase embedded in it. If you have an SSL certificate key file, you canuse it for SAML aswell. See About the Certificate File for details.
IdP account that supports SAML 2.0: You need an account with an external identityprovider. Some examples are PingFederate, SiteMinder, andOpen AM. The IdP must supportSAML 2.0.
IdP provider that supports import/export of XML metadata: Your identity provider mustsupport the import and export of XMLmetadata files. Manually generated filesmay appear towork, but Tableau Software Technical Support cannot assist with manual IdP metatdata filegeneration or troubleshooting.
Attribute named username: Youmust configure your identity provider to return an attributenamed username in the SAML response. To change this default attribute to something else,use the tabadmin setting wgserver.saml.idpattribute.username. You will need to change thedefault attribute if you use a global ID.
No Single Logout: Tableau Server does not support SAMLSingle Logout (SLO).Matching usernames: Tableau Server usernames and the usernames stored in the IdP mustmatch. For example, if the username for Jane Smith is stored in PingFederate as jsmith, it mustalso be stored in Tableau Server as jsmith. If you are configuring SAML as part of TableauServer Setup, part of Setup is creating the Tableau Server administrator account. Before yourun Setup, make sure that the account you plan to use exists in your IdP. If you are using ActiveDirectory authentication with Tableau Server and havemultiple Active Directory domains(users belong tomultiple domains or your Tableau Server installation includesmultipledomains), the IdP must send both the domain and username for a user, and thesemust matchthe user exactly in Tableau Server (these can be sent either as domain/username orusername@domain).
- 292 -
HTTP POST: Tableau Server only accepts HTTP POSTs for SAML communications. HTTPRedirect and HTTP SOAP are not supported.
SP-initiated: Tableau Server only supports SAML authentication that begins at the serviceprovider (SP).
No Active Directory automatic logon: If you are using SAML, and Tableau Server isconfigured to use Active Directory for user management, you cannot useEnable automaticlogon.IdP provider that uses forms-based authentication: Tableau Desktop requires forms-based authentication. If your IdP does not support forms-based authentication you can disableSAML for Tableau Desktop with the wgserver.authentication.desktop_nosamlcommand. See tabadmin set options on page 358 for more information.
Distributed installations only: Clusters configured for SAMLmust have the sameSAML certificate, SAML key, and SAML IdP metadata files on each Tableau Serverthat's running an application server process. See Configure a Server Cluster for SAMLfor details.
About the Certificate FileIf you are using a PEM-encoded x509 certificate file for SSL, you can use the same file forSAML.When it's used for SSL, the certificate file is used to encrypt traffic. When it's used forSAML, the certificate is used for authentication.
Tableau Server does not support certificate and certificate key files for SAML if thecertificate/key require a chain file. If your SSL certificate and certificate key file require a chainfile, you need to generate a new certificate and key file to use for SAML.
SAMLYou can configure Tableau Server to use an external identity provider (IdP) to authenticateTableau Server users over SAML. All user authentication is done outside of Tableau,regardless of whether you're using Active Directory or local authentication in Tableau Server tomanage your user accounts on Tableau Server. This allows you to provide a single sign-onexperience across all the applications in your organization.
Before you configure Tableau Server for SAML, make sure youmeet theSAMLRequirements on the previous page.
Configure SAMLTo configure Tableau Server to use SAML:
1. Place the certificate files in a folder named SAML, parallel to the Tableau Server 8.2folder. For example:
- 293 -
C:\Program Files\Tableau\Tableau Server\SAML
This location gives the account that's running Tableau Server the necessary permissionsfor the files.
2. SAML configuration is handled on theSAML tab, which displays during Tableau ServerSetup. If you are configuring SAML after Setup, access the SAML tab by opening theTableau Server Configuration Utility (Start > All Programs > Tableau Server 8.2 >Configure Tableau Server) and clicking theSAML tab.
3. On the SAML tab, selectUse SAML for single sign-on and provide the location foreach of the following:
Tableau Server return URL—TheURL that Tableau Server users will be accessing,such as http://tableau_server. Using http://localhost is not recommended, and an URLwith a trailing slash (for example, http://tableau_server/) is not supported.SAML entity ID—The entity ID uniquely identifies your Tableau Server installation tothe IdP. You can enter your Tableau Server URL again here, if you like, but it does nothave to be your Tableau Server URL.
SAML certificate file—APEM-encoded x509 certificate with the file extension .crt.This file is used by Tableau Server, not the IdP.
SAML certificate key file—AnRSA or DSA private key file that is not passwordprotected, and that has the file extension .key. This file is used by Tableau Server, notthe IdP.
4. Leave theSAML IdP metadata file text box empty for now and clickExport MetadataFile.
- 294 -
5. A dialog opens that allows you to save Tableau Server's SAML settings as an XML file.At this point, metadata from your IdP is not included.
Save the XML file with the name of your choice.
6. On your IdP's website or in its application:
l Add Tableau Server as a Service Provider.You will need to refer to your IdP'sdocumentation on how to do this. As part of this, you will import the file you savedin step 5.
l Confirm that your IdP usesusername as the attribute element to verify.7. Still within your IdP, export your IdP'smetadata XML file.
8. Copy your IdP'smetadata XML file to the following folder on your Tableau Servercomputer:
C:\Program Files\Tableau\Tableau Server\SAML
9. On the SAML tab in the Tableau Server Configuration dialog box, enter the location tothe file in theSAML IdP metadata file text box:
10. ClickOK. Tableau Server is now configured for SAML authentication.
Configure a Server Cluster for SAMLWhen you configure a Tableau Server cluster to use SAML, you place the same SAMLcertificate, SAML key, and SAML IdP metadata files on every computer that's running aTableau application server process (also known aswgserver). To configure a Tableau Servercluster to use SAML:
- 295 -
1. Configure the primary Tableau Server as described in the procedure above.
2. Place the same SAML certificate, SAML key, and SAML IdP metadata files that youused for the primary on each TableauWorker that is running an application serverprocess. Use the same folder location on the workers that you used on the primary. Youdo not need to do any additional configuration on the workers.
Take, as an example, a cluster that includes a primary Tableau Server and threeworkers. Application server processes are running on the primary, Worker 2 andWorker3. In this situation, you configure the primary Tableau Server for SAML, then copy thesame SAML certificate, SAML key, and SAML IdP metadata files toWorker 2 andWorker 3. Because these files are in the C:\ProgramFiles\Tableau\TableauServer\SAML folder on the primary, they are in that same location onWorker 2 andWorker 3.
Test Your ConfigurationTest your SAML configuration by opening a fresh web browser instance and typing theTableau Server name in the URLwindow:
You should note that the sign in prompt that appears is from your IdP and not Tableau Server:
- 296 -
Troubleshoot SAMLUse the following topics to troubleshoot SAML issues.
SAML and Enable Automatic LogonIf you are using SAML and Tableau Server is also configured to use Active Directory, do notalso selectEnable automatic logon. Enable automatic logon and SAML cannot both beused.
Signing In from the Command LineEven if Tableau Server is configured to use SAML, it is not used if you sign in to Tableau Serverusing the command line tools tabcmd on page 319 or the Tableau Data Extract command lineutility (provided with Tableau Desktop).
Login FailedIf you receive themessage "Login failure: Identity Provider authentication successful for user<username from IdP>. Failed to find the user in Tableau Server." the usernames as stored inTableau Server and as stored in your IdP are not identical. To fix this, make sure that theymatch. For example, if Jane Smith's username is stored in the IdP as jsmith it must be storedin Tableau Server as jsmith.
SAML Error LogSAML authentication takes place outside Tableau Server, so troubleshooting authenticationissues can be difficult, but any login attempts are logged by Tableau Server. You can create asnapshot of log files and use them to troubleshoot problems. For more information, seeArchive Log Files on page 375.
Note: Normal SAML events are only logged if wgserver.log.level is set to debug.For more information, seeChange Logging Levels on page 385.
Check for SAML errors in the following files in the unzipped log file snapshot:
\wgserver\wgserver-<n>.log
\wgserver\production.<nnnn>_<yyyy_mm_dd_hh_mm_ss>.log
Trailing SlashOn the SAML tab, confirm that the Tableau Server return URL does not end with a trailingslash (correct: http://tableau_server; incorrect: http://tableau_server/):
- 297 -
Confirm ConnectivityConfirm that the Tableau Server you are configuring has either a routeable IP address or aNAT at the firewall that allows two-way traffic directly to the server.
You can test your connectivity by running telnet on Tableau Server and attempting to connectwith the SAML IdP. For example: C:\telnet 12.360.325.10 80
The above test should connect you to the HTTP port (80) on the IdP and you should receive anHTTP header.
- 298 -
Run As UserYou can use a dedicated Active Directory (AD) user account for the Tableau Server service torun under, called a Run AsUser account. Some administrators choose to do this whenpublished workbooks on Tableau Server connect to live data sources. The server's defaultNetwork Service account (NT AUTHORITY\NetworkService) doesn't have the correctpermissions for connecting to data sources on other computers. A correctly configured ADaccount does.
For data sources that require NT authentication, the AD account can also automatically handlethe authentication process, thus shielding users from prompts for credentials when theworkbook connects to the live data source. Finally, a Run AsUser AD account that is dedicatedto a specific resource is often less problematic to manage than an AD account associated witha person.
To configure Tableau Server to use a Run AsUser account, follow the procedures below. Ifyou are running a distributed installation of Tableau Server, these steps should be performedon workers aswell as on the primary. Also note that the steps underRun As AccountSettings to Confirm on page 301may vary from site to site.Note:If you are installing Tableau Server with your Run AsUser account in hand, before you runSetup, confirm that theWindowsSecondary Login service has the correct values for LogOnand Startup. SeeVerify Tableau Service Settings on the next page for more information.
Identify the AccountYour first step is to identify or create an Active Directory account for the Tableau Server serviceto run under. This will be the Tableau Server's Run AsUser account, and it should have thefollowing:
l Permissions for connecting to the data source with at least read access.
l Credentials to allow Tableau Server to satisfy the NT authentication processwith thedata source. Microsoft data sources that performNT authentication includeMicrosoftSQL Server andMicrosoft Analytical Services (MSAS), but not Access or Excel.
l Permissions to query your Active Directory domain controller for users and groups. Auser account created on the local machine that Tableau Server is running on probablywon’t have these permissions.
Confirm Domain Two-Way TrustConfirm that there is a two-way trust between domains if any of the following are true:
l Themachines hosting the Tableau Server and the data source are on separatedomains.
- 299 -
l Tableau Server users are on a separate domain from Tableau Server or the datasource.
Verify Tableau Service SettingsConfirm that Tableau services are assigned the correct LogOn and Startup values. If you arerunning a distributed installation of Tableau Server, perform these steps on the workers aswellas on the primary.
1. Log on as administrator to the computer running Tableau Server.
2. On the Tableau Server computer, selectStart > Control Panel > AdministrativeTools > Computer Management > Services and Applications > Services.
3. Open Services and Applications, then clickServices. Confirm that the following serviceshave the correct settings:
Service Name Logon ValueStartupValue
FLEXnet Licens-ing Service
Local System Manual
SecondaryLogin
Local System Automatic
Tableau Server(tabsvc)
<domain>\<username> This is the RunAs user account. See below.
Automatic
Tablicsrv Local System Automatic
Note: Do not change the default settings on theRecovery tab of the Tableau ServerApplication Manager Properties dialog box; leave the settings for failure recovery asTake No Action. If you change these settings, Tableau Server will restart after beingstopped via the tabadmin command or Stop Tableau Server command.
Changing the Log On ValueTo change the Log On value for Tableau Server (tabsvc) to the Run AsUser account:
1. SelectStart > All Programs > Tableau Server > Stop Tableau Server.2. SelectStart > All Programs > Tableau Server > Configure Tableau Server.3. On theGeneral tab, enter the domain, username, and password for Tableau Server's
Run AsUser account.
4. ClickOK, and then selectStart > All Programs > Tableau Server > Start TableauServer.
- 300 -
Prepare the Local Security PolicyIf your Run AsUser account isn't an administrator on the Tableau Server machine (primaryand workers, if you're running a distributed installation), youmust prepare themachine's localsecurity policy so that the Tableau Server Run AsUser account can log onto themachine as aservice andmake configuration changes. To do this:
1. SelectStart > Control Panel > Administrative Tools > Local Security Policy.2. In the Local Security Settingswindow, open Local Policies, highlight User Rights
Assignments, then right-clickLog on as a service and selectProperties.
3. In the Log on as a service Properties window, clickAdd User or Group.4. Type the <domain>\<username> for the Tableau Server Run AsUser account (for
example: MYCO\tableau_server), and clickCheck Names.5. When the account resolves correctly, it is underlined. ClickOK.6. Repeat these steps to add the Run As account to theAllow log on locally policy.7. Repeat these steps to remove the Run As account from theDeny log on locally policy.8. ClickOK to close the Local Security Settingswindows.
- 301 -
Configure Data Source Connection SettingsTo automatically authenticate your users when the workbook they're accessing connects to alive, NT-authenticated data source, configure your Tableau data connection with theUseWindows NT Integrated security option selected:
Windows NT Integrated Security Username and PasswordAuthenticateswith the server’s Run AsUseraccount
Each Tableau Server user is prompted fordatabase credentials
Run As Account Settings to ConfirmTheRun AsUser account needs permissions that allow it to read, execute, and sometimesmodify files. Depending on the account you used as a starting point, it may already have thecorrect permissions. Any time you change the server's Run As account you should confirm thatit meets the following requirements. If you're running a distributed installation, this applies toboth the primary and workers.
Grant Read and Execute PermissionsThe account the Tableau Server service runs under needs permission to read and executefiles. Any time the server's Run AsUser account is changed, confirm or configure the following:
1. On themachine hosting Tableau Server (and TableauWorker, if distributed), useWindowsExplorer to right-click the drive on which Tableau is installed, such asLocalDisk (C:), and selectProperties.
2. In the Local Disk PropertiesWindow, select theSecurity tab.3. ClickEdit, thenAdd.4. In the Select Users, Computers, Service Accounts, or Groups dialog box, type the
<domain>\<username> for the Tableau Server Run AsUser account. Do not use agroup account.
5. ClickCheck Names to resolve the account, thenOK to confirm.
- 302 -
6. With the Tableau Server Run AsUser account highlighted, confirm that it hasRead &execute permissions. SelectingRead & execute automatically selectsList foldercontents andRead.
7. ClickOK to exit.
Grant Modify PermissionsThe account also needs the ability to do things like create log files. Confirm or configure thefollowing:
1. Navigate to the following folders:
C:\Program Files\TableauC:\ProgramData\Tableau\
If you are running the 32-bit Tableau Server on a 64-bit operating system, you willneed to go to C:\Program Files (x86)\Tableau instead ofC:\Program Files\Tableau. Also, the above drive and pathsmay varydepending on where Tableau Server is installed.
2. Right-click the folder, selectProperties, and click theSecurity tab:l ClickEdit, thenAdd.l Type the <domain>\<username> for the Tableau Server Run AsUseraccount.
l ClickCheck Names to resolve the account, thenOK to confirm.
l With the Tableau Server Run AsUser account highlighted, confirm that it hasModify permissions. SelectingModify automatically grants all permissions
- 303 -
except for Full Control andSpecial Permissions:
3. For each folder from step 1 above, on the Tableau Properties Security tab, clickAdvanced:
- 304 -
4. In the Advanced Security Settings for Tableau window, clickChange Permissions.5. In the Advanced Security Settings for Tableau dialog box, highlight the Run AsUser
account and select theReplace all child object permissions with inheritablepermissions from this object check box:
- 305 -
6. ClickOK to apply changes to all subfolders and files - thismay take a few minutes. It'stypical to receive several error messages fromWindowswhen you apply these changes.There's no need to cancel the process; instead, clickContinue.
7. ClickOK to confirm changes, then clickOK in the Tableau Properties dialog box.
Modify Registry Settings
The following step is optional and not seen inmost environments. If the registry security ishighly restrictive, grant the Tableau Server Run AsUser account read and write permissions tothe registry branches listed below. The registry keys vary according to whether you installedthe 32- or 64-bit version of Tableau Server and, in the case of the 32-bit Tableau Server,whether you installed on a 32- or 64-bit operating system. The 64-bit Tableau Server can onlybe installed on a 64-bit operating system.64-bit Tableau Server Installations
l HKEY_CURRENT_USER\Software\Tableau
l HKEY_LOCAL_MACHINE\Software\Tableau
32-bit Tableau Server Installations
l HKEY_CURRENT_USER\Software\Tableau
and
- 306 -
l 32-bit operating systems: HKEY_LOCAL_MACHINE\Software\Tableau
l 64-bit operating systems: HKEY_LOCAL_MACHINE\Software\Wow6432Node\Tableau
- 307 -
SQL Server ImpersonationImpersonation is when one user account acts on behalf of another user account. You canconfigure Tableau andMicrosoft SQL Server to perform database user impersonation, so thatthe SQL Server database account used by Tableau Server queries on behalf of SQL Serverdatabase users, who are also Tableau users.
Themain benefit of this feature is it allows administrators to implement and control their datasecurity policy in one place: their databases.When Tableau users access a view with a liveconnection to a SQL Server database, the view only displayswhat the users' databasepermissions authorize them to see. An additional benefit is that the users don't have to respondto a database login prompt when they access the view. Also, workbook publishers don't haveto rely on user-specific filters to restrict what's seen in views.
Use the topics below for more information on what you need to use this feature.
Impersonation RequirementsHere’s what you need to use feature:
l Live connections to SQL Server only: Impersonation can only be used for views thathave a live connection to a SQL Server database, version 2005 or newer.
l Individual database accounts: Each person who’ll be accessing the view must havean explicit, individual account in the SQL Server database to which the view connects.Members of an Active Directory (AD) group cannot be impersonated. For example, ifJane Smith is amember of the AD group Sales, and her database administrator addsthe Sales AD group to the SQL Server database, Jane cannot be impersonated.
l Matching credentials and authentication type: The credentials of each Tableauuser's account and their Tableau user authentication typemust match their credentialsand authentication type in the SQL Server database. In other words, if Jane Smith’sTableau Server user account has a username of MyCo\jsmith and Tableau Server isusing Active Directory for user authentication, her username on the SQL Serverdatabasemust also beMyCo\jsmith and SQL Server must be usingWindows IntegratedAuthentication.
l SQL Server prerequisites: In SQL Server you should have a data security table, aview that enforces data security, and you should require that your database users usethe view.
l SQL IMPERSONATE account: You need a SQLServer database account that hasIMPERSONATE permission for the above database users. This is either an accountwith the sysadmin role or one that has been granted IMPERSONATE permission foreach individual user account (see theMSDN article on EXECUTE AS). This SQLServer account must also be one of two accounts on the Tableau side of things:
l The Tableau Server Run AsUser account (see Impersonate with a Run AsUser Account on the next page).
- 308 -
l Theworkbook publisher's account (see Impersonate with Embedded SQLCredentials on page 310).
How Impersonation WorksHere’s an illustration of how database user impersonation works:
In the above illustration, Jane Smith (MyCo\jsmith) is aWest Coast sales representative andHenryWilson (MyCo\hwilson) covers the East. In the SQL Server database, the accountpermissions for Jane's account, MyCo\jsmith, only give her access toWest Coast data.Henry's account, MyCo\hwilson, can only access data for the East Coast.
A view has been created that displays data for the entire country. It has a live connection to aSQL Server database. Both users sign in to Tableau Server and click the view. Tableau Serverconnects to SQL Server using a database account with IMPERSONATE permission for eachuser's database account. This account acts on behalf of each user's database account.
When the view displays, it is restricted by each user's individual database permissions: Janesees only theWest Coast sales data, Henry sees only the East Coast data.
Impersonate with a Run As User AccountImpersonating via a Run AsUser account is the recommendedway to peform impersonation.The Run AsUser account is an AD account the Tableau Server service can run under on themachine hosting Tableau Server (seeRun As User on page 298). This same account musthave IMPERSONATE permission for the database user accounts in SQL Server. From a datasecurity standpoint, using the Tableau Server Run As account for impersonation gives theadministrator themost control.
To set up impersonation with a Run AsUser account:
1. When you configure Tableau Server as part of Setup, under Server Run As User,enter the Run AsUser AD account that has IMPERSONATE permission for the user
- 309 -
accounts. Under User Authentication, selectUse Active Directory:
2. ClickOK to finish configuration.
3. Create a workbook in Tableau Desktop.When you create the data connection, selectUse Windows NT Integrated security for the workbook's live connection to a SQLServer database:
4. In Tableau Desktop, publish the workbook to Tableau Server (Server > PublishWorkbook).
5. In the Publish dialog box, click Authentication, then in the Authentication dialog box,select Impersonate via server Run As account from the drop-down list:
- 310 -
6. ClickOK.7. Test the connection by signing into Tableau Server as a user. When you click a view, you
should not be prompted for database credentials and you should only see the data theuser is authorized to see.
Impersonate with Embedded SQL CredentialsYou can also perform impersonation by having the person who publishes a view embed theirSQL Server account credentials in the view. Tableau Server can be running under any type ofaccount, but it will use these credentials, supplied by the publisher, to connect to the database.
Thismay be the right choice for your site if the account that handles the impersonation cannotbe an AD account and if you’re comfortable giving workbook publishers an account with apotentially high permission level on SQL Server.Note:To use this approach, Embedded Credentialsmust be enabled on Tableau Server:
- 311 -
To impersonate with the workbook publisher’s SQL account:
1. In Tableau Desktop, create a workbook.When you create the data connection, selectUse a specific username and password for the workbook's live connection to a SQLServer database:
2. Publish the workbook to Tableau Server (Server > Publish Workbook).3. In the Publish dialog box, click Authentication, then in the Authentication dialog box,
select Impersonate via embedded password from the drop-down list:
4. ClickOK.
- 312 -
5. Test the connection by signing in to Tableau Server as a user. When you click a view,you should not be prompted for database credentials and you should only see the datathe user is authorized to see.
- 313 -
TCP/IP PortsThe following table lists the ports that Tableau Server uses by default, and whichmust beavailable for binding. If Windows Firewall is enabled, Tableau Server will open the ports itneeds—you do not need to do it yourself (for distributed installationswith a worker runningWindows 7, refer to the Tableau Knowledge Base).
Dynamic port remapping
When dynamic port remapping is enabled (the default), Tableau Server first attempts to bind tothe default ports, or to user-configured ports if they are defined. If the ports are not available,Tableau Server attempts to remap processes to other ports, starting at port 8000. The gatewayport and ssl port are not remapped.When next restarted, Tableau Server will revert to usingthe default or configured ports.
When dynamic port remapping is disabled, Tableau Server does not attempt to remapprocesses and if a conflict is detected, Tableau Server will not start.
You can disable dynamic port remapping using the tabadmin set service.port_remapping.enabled command. For more information, see tabadmin set options onpage 358.
PortUsed by this server pro-cess...
TYPE OF INSTALLATION
ParameterAll DistributedHigh Avail-
ability
80 Gateway. X gateway.public.port,worker0.gateway.port
443
SSL.When TableauServer is configured forSSL, the applicationserver redirects requeststo this port.
X --
3729 Tableau Server Setup. X --
3730-3731
Tableau worker servers indistributed and highlyavailable environments(the primary TableauServer does not listen onthese ports).
X X --
8000 -8059
Application server (baseport 8000). Consecutiveports after 8000 are used,up to the number of pro-cesses. By default,Tableau Server installs
X wgserver.port
- 314 -
PortUsed by this server pro-cess...
TYPE OF INSTALLATION
ParameterAll DistributedHigh Avail-
ability
with two applicationserver processes (ports8000 and 8001).
8060 PostgreSQL database. X pgsql.port
8061 Firebird. X firebird.port
8062
Process that performs dis-covery in a distributedenvironment that’s beenconfigured for high avail-ability.
X pgsql.initport
8080 Solr and Tomcat HTTP. X solr.port, tom-cat.http.port1
8250 Background tasks. X backgrounder.port
8755 Tableau Administrativeprocess. X tabadminservice.port
9090
Process that performs rep-lication in a distributedenvironment that’s beenconfigured for high avail-ability.
X rsync.port
9100 -9199
VizQL server (base port9100). Consecutive portsafter 9100, up to the num-ber of processes, are alsoused. By default, TableauServer installs with twoVizQL Server processes(ports 9100 and 9101).
X vizqlserver.port
9700 -9899
Data server (base port9700). Consecutive portsafter 9700, up to the num-ber of processes, are alsoused. By default, TableauServer installs with two
X dataserver.port
1These parametersmust be set to the same value.
- 315 -
PortUsed by this server pro-cess...
TYPE OF INSTALLATION
ParameterAll DistributedHigh Avail-
ability
data server processes(ports 9700 and 9701).
27000-27009
Workers and primaryserver to communicatelicensing information in dis-tributed and highly avail-able environments.
X X --
One additional port isdynamically chosen forworkers and the primaryserver to communicatelicensing information in dis-tributed and highly avail-able environments.Instead, you can specify afixed port (27010 is recom-mended). See theTableau Knowledge Basefor details. Installationswhere the primary serveris in a DMZmust usethese directions.
X X --
27042
Data engine. TableauServer installs with onedata engine process.There can be up to twodata engine processesper node, on up to twonodes in a cluster.
X dataengine.port
27043
Data engine initializationin a distributed envir-onment that’s been con-figured for highavailability.
X
Edit the Default PortsYou canmodify the default ports used by Tableau Server processes by using the commandline administrative tool, tabadmin on page 338. For example, the default port for the
- 316 -
application server process (wgserver) is 8000. You can use the tabadmin parameterworkerX.wgserver.port to change it to a different port. Follow the steps below to changethe Tableau Server port configuration. If you are enabling the server's JMX ports, seeEnablethe JMX Ports on the next page
1. Open a command prompt as an administrator and type the following:
cd “C:\Program Files\Tableau\Tableau Server\8.2\bin”
2. Modify a port value by typing the following:
tabadmin set <workerX>.<parameter> <new port value>
In the above command, <workerX> refers to themachine whose port you want tochange, <parameter> is one of the values in the table below (a server process’ port,such as wgserver.port), and <new port value> is the new port number youwant the server process to use. If Tableau Server is running on onemachine,<workerX> is worker0. If you’re running a cluster, worker0 is the primary,worker1 is your first worker server, worker2 is your second, and so on. In this lastcase, you would need to run the command (from a command prompt on the primary)once for eachmachine in the cluster.
Here’s an example that sets the port on the primary or a standalone server to 8020 forthe application server process (wgserver):
tabadmin set worker0.wgserver.port 8020
The following example sets the port for a 3-machine cluster (one primary and twoworkers) to 9200 for the VizQL server process.
tabadmin set worker0.vizqlserver.port 9200
tabadmin set worker1.vizqlserver.port 9200
tabadmin set worker2.vizqlserver.port 9200
You can use the following parameters tomodify the corresponding ports—see TCP/IPPorts on page 313 for a complete list of tabadmin parameters that can be set.
Port to Change Parameter
80 gateway.public.port, worker0.gateway.port
8000 wgserver.port
8060 pgsql.port
8080 solr.port, tomcat.http.port1
1These parameters should be set to the same value.
- 317 -
Port to Change Parameter
9100 vizqlserver.port
9700 dataserver.port
3. After youmake the necessary port configuration changes, restart Tableau Server bytyping the following:
tabadmin restart
While the server is restarting it will be unavailable to all users. Be sure to warn your usersof the outage prior to this operation or schedule thismaintenance during non-businesshours.
Enable the JMX PortsTo help you work through a problemwith Tableau Server, Tableau Support may ask you toenable the server's JMX ports. These ports can be useful for monitoring and troubleshooting,usually with a tool like JConsole.
To enable the JMX ports on Tableau Server:
1. Stop the server.
2. Enter the following command:
tabadmin set service.jmx_enabled true
3. Enter the configure command:
tabadmin configure
4. Start the server.
JMX Port ListHere's the list of JMX ports, all of which are disabled by default. When these ports are enabled,they are used for all types of installations: single-server, distributed, and highly available:
Port Used by this server process... Parameter
8300 -8359
Application server JMX. Determined by the applicationserver port(s) + 300. --
8550 Backgroundmonitor JMX. Determined by the back-ground port of 8250 + 300. --
9095 Servicemonitor JMX. svcmonitor.jmx.port
9400 - VizQL server JMX. Determined by the VizQL server --
- 318 -
Port Used by this server process... Parameter
9499 port(s) + 300.
10000 -10299
Data server JMX. Determined by the data server port(s) + 300. --
How the JMX Ports are DeterminedThe JMX ports for the application server (8300 - 8359), backgrounder (8550), VizQL server(9400 - 9599), and the data server (10000 - 10299) are assigned using the formula “base port+ 300” (see TCP/IP Ports on page 313 for a list of the default base ports). In addition, if therearemultiple instances of a process, each will have a JMX port. For example, if you configureTableau Server to run four instances of the application server process, ports 8000 (defaultbase port), 8001, 8002, and 8003 are used. Application server JMX ports 8300 (base port +300), 8301, 8302, and 8303 are then bound to their respective process instances.
Even though they’re not directly used by Tableau Server, if a JMX port is being used by anotherapplication, Tableau Server processeswon’t run. In addition, JMX ports cannot be editeddirectly using tabadmin. You change a JMX port by changing the base port for its process. Inother words, if port 10000 isn’t available for the data server JMX process, you use tabadmin (asdescribed inEdit the Default Ports on page 315) to change the data server base port from9700 to 9800. This will move the data server JMX port to 11000.
To reduce security risks, it’s a good practice to configure your firewall to block outside traffic tothe JMX ports.
Restore the Default Value for a PortYou can restore the default value for a port by following the procedure below:
1. Open a command prompt as an administrator and type the following:
cd “C:\Program Files\Tableau\Tableau Server\8.2\bin”
2. Restore the default port value by typing the following:
tabadmin set <workerX>.<parameter> --default
If Tableau Server is running on onemachine, <workerX> is worker0. If you’rerunning a cluster, worker0 is the primary, worker1 is your first worker server,worker2 is your second, and so on.
Here’s an example:
tabadmin set worker0.wgserver.port --default
3. Restart Tableau Server by typing the following:
tabadmin restart
- 319 -
tabcmdThe tabcmd utility is one of the two command line tools that installs with Tableau Server (theother is tabadmin on page 338). The commands provided through tabcmd can help youautomate common tasks, such as publishing workbooks in batches and administering usersand groups. The tabcmd utility installs in the Tableau Server bin folder (C:\ProgramFiles\Tableau Server\8.2\bin), but you can install and run tabcmd on another machine aswell.See the topics below for more information:
Install tabcmdBy default, the tabcmd command line utility installs with Tableau Server to the server's binfolder (for example, C:\Program Files\Tableau\Tableau Server\8.2\bin). Youcan run it from there. For administrative flexibility, you can also install it on another machine.
If you installed the tabcmd command line utility on computers that are not running TableauServer and you are upgrading Tableau Server to a new major version (version 8.1 to version8.2 for example), Tableau recommends you also upgrade standalone installations of tabcmd toavoid any potential incompatibilities between versions.
To install tabcmd on another machine:
1. Navigate to the extras folder on Tableau Server:
C:\Program Files\Tableau\Tableau Server-\8.2\extras\TabcmdInstaller.exe
2. Copy TabcmdInstaller.exe to the computer where you want to install it.
3. Double-click TabcmdInstaller.exe to run it.
4. Follow the prompts to install tabcmd.
Because tabcmd is a command line tool, and due to some limitationswith theWindowsoperating system, Tableau recommends that you install tabcmd in a folder namedtabcmd at the root of the C:\ drive (C:\tabcmd).
Running the tabcmd Setup program does not automatically add tabcmd to theWindowsPATH variable, you will need to either explicitly call tabcmd using its full path or add itsdirectory to the PATH variable.
How to Use tabcmdThe first step to using tabcmd is to open a command prompt as an administrator. You thennavigate to Tableau Server's bin folder (for example, C:\ProgramFiles\Tableau\TableauServer\8.2\bin) or include that location in your commands.
- 320 -
To use tabcmd to perform tasks on Tableau Server, youmust establish an authenticatedserver session. The session identifies the Tableau Server and the Tableau Server user who'srunning the session. You can start a session first, then specify your command next, or you canstart a session and execute a command all at once. If you are using tabcmd to performmorethan one task, theymust be run one after the other (serially), not in parallel.
The following command demonstrates starting a session with the Tableau Server namedtabserver.myco.com:
tabcmd login -s http://tabserver.myco.com -u admin -p p@ssw0rd!
As you use tabcmd commands, note that the commands (such as login) and theoptions (such as -s, -u, etc.) are not case sensitive, but the values you provide (suchas p@ssw0rd or [email protected]) are case sensitive.
This command that deletes a workbook namedSales_Workbook located in the same directoryas tabcmd:
tabcmd delete "Sales_Workbook"
Here's how to accomplish all of the above with one command—note that you don't needlogin here:
tabcmd delete "Sales_Workbook" -s http://tabserver.myco.com -uadmin -p p@ssw0rd!
A Tableau Server can runmultiple sites. When a workbook is on the Default site of amulti-siteserver you don't need to specify Default, the above command is sufficient. However, if thecommand applies to something on a site other than Default, you need to specify the site ID forthat site (see login on page 332). Here's the same command for a workbook that's on theWest Coast Sales site (site ID wsales):
tabcmd delete "Sales_Workbook" -s http://tabserver.myco.com -twsales -u admin -p p@ssw0rd!
The options -s, -t, -u, and -p are among tabcmd's global variables, whichmeans they canbe used with any command.
When the command is successful, tabcmd returns a status code of zero. A full error messagefor non-zero status codes is printed to stderr. In addition, informative or progressmessagesmay be printed to stdout. A full log named tabcmd.log that includes debugging, progress, anderror messages is written to:
l WindowsServer 2012,WindowsServer 2008 R2,WindowsVista, Windows 7,Windows 8: C:\Users\<username>\AppData\Local\Tableau
l WindowsServer 2003: C:\Documents and Settings\<username>\ApplicationData\Tableau
- 321 -
tabcmd Global OptionsThe table below shows the options that are used by all commands. The --server, --user,and --password options are required at least once to begin a session. An authenticationtoken is stored so subsequent commands can be run without including these options. Thistoken remains valid for fiveminutes after the last command that used it.
Option(short)
Option(long)
Argument Description
-h --help Displays the help for the command.-s --server Tableau
ServerURL
Required at least once to begin session.
-u --user TableauServerusername
Required at least once to begin session.
-p --pass-word
TableauServerpassword
Required at least once to begin session.You can alternatively use the -P option.
--pass-word-file
filename.txt Allows the password to be stored in thegiven file rather than the command line forincreased security.
-t --site TableauServer siteID
Indicates that the command applies to thesite specified by the site ID. If you do notspecify a site, the Default site is assumed.Applies only to servers with multiple sites.
-x --proxy Host:Port Uses the specified HTTP proxy.--no-prompt
When specified, the commandwill notprompt for a password. If no valid pass-word is provided the commandwill fail.
--no-proxy
When specified, an HTTP proxywill not beused.
--no-cert-check
When specified, tabcmd (the client) doesnot validate the server's SSL certificate.
--[no-]cookie
When specified, the session id is saved onlogin so subsequent commandswill notneed to log in. Use the no- prefix to notsave the session id. By default the sessionis saved.
--timeout seconds Waits the specified number of seconds forthe server to complete processing the com-mand. By default the processwill timeout in
- 322 -
Option(short)
Option(long)
Argument Description
30 seconds.
tabcmd CommandsHere are the commands that can be used with the tabcmd command line tool:
addusers group-name exportcreategroup group-name get urlcreateproject project-name listsitescreatesite site-name logincreatesiteusers filename.csv logout
createusers filename.csv
publish file-name.twb(x),-filename.tds(x),or filename.tde
delete workbook-name or datasource-name
refreshextractsworkbook-name or data-source-name
deletegroup group-name removeusersgroup-name
deleteproject project-name runscheduleschedule-name
deletesite site-name set setting
deleteusers filename.csv syncgroupgroup-name
editsite site-name version
addusers group-nameAdds the users listed in the --users argument to the group with the given group-name.
Example
tabcmd addusers "Development" --users "users.csv"
Option(short)
Option (long) Argument Description
--users filename.csv Add the users in the given file to thespecified group. The file should bea simple list with one username perline. The users should already be
- 323 -
Option(short)
Option (long) Argument Description
created on Tableau Server. Seealso Import Users from a CSVFile on page 70.
--[no-]complete When set to complete this optionrequires that all rows be valid forany change to succeed. If not spe-cified, --complete is used.
creategroup group-nameCreates a group with the given group name. Use addusers (for local groups) andsyncgroup (for Active Directory groups) commands to add users after the group has beencreated.
Example
tabcmd creategroup "Development"
createproject project-nameCreates a project with the given project name.
Example
tabcmd createproject -n "Quarterly_Reports" -d "Workbooks showingquarterly sales reports."
Option(short)
Option (long) Argument Description
-n --name name Specify the name of the project thatyou want to create.
-d --descrip-tion
description Specify a description for the project.
createsite site-nameCreates a site with the given site name.
ExamplesCreate a site namedWest Coast Sales. A site ID of WestCoastSaleswill be automaticallycreated, the site will have no storage quota limit, and site administrators will be able to add andremove users:
tabcmd createsite "West Coast Sales"
- 324 -
Create a site named West Coast Sales with a site ID of wsales:
tabcmd createsite "West Coast Sales" -r "wcoast"
Prevent site administrators from adding users to the site:
tabcmd createsite "West Coast Sales" --no-site-mode
Set a storage quota, in MB::
tabcmd createsite "West Coast Sales" --storage-quota 100
Option(short)
Option(long)
Argument Description
-r --url site ID Used in URLs to specify the site. Different from thesite name.
--user-quota
number of users Maximumnumber of users that can be added to thesite.
--[no-]site-mode
Allow or deny site administrators the ability to addusers to or remove users from the site.
--storage-quota
number of MB InMB, the amount of workbooks, extracts, and datasources that can be stored on the site.
createsiteusers filename.csvThis command allows site administrators to add users to a site. It creates users on the currentsite, using the given comma separated values (CSV) file. The file may have the followingcolumns, in the order shown below:
1. Username
2. Password
3. Full Name
4. License Level (interactor/viewer/unlicensed)
5. Administrator (site/none)
6. Publisher (yes/true/1 or no/false/0)7. Email Address
The file can have fewer columns. For example it can be a simple list with one username perline. When the server is using Active Directory authentication, the Password column isignored. Quotesmay be used if a value contains commas. See Import Users from a CSVFile on page 70 for other details.Example
- 325 -
tabcmd createsiteusers "users.csv" --license "Interactor" --publisher
Option(short)
Option(long)
Argument Description
--nowait Do not wait for asynchronous jobs tocomplete.
--silent-progress
Do not display progressmessages forasynchronous jobs.
--license Interactor, Viewer, orUnlicensed
Sets the default license level for allusers. This settingmay be overridden bythe value in the CSV file.
--admin-type
Site orNone
Assigns or removes the site admin rightto all users in the CSV file. This settingmay be overridden by the value in theCSV file. The default is None for newusers and unchanged for existing users.System administrators cannot be cre-ated or demoted using cre-atesiteusers (use createusersinstead).
--[no-]publisher
Assigns or removes the Publish right toall users in the CSV file by default. Thissettingmay be overridden by the value inthe CSV file. The default is no for newusers and unchanged for existing users.
--[no-]complete
Require (or not require) that all rows bevalid for any change to succeed. Bydefault, --complete option is used.
createusers filename.csvCreates the users listed in the given comma separated values (CSV) file. This command canonly be used by system administrators. The file may have the following columns, in the ordershown below:
1. Username
2. Password
3. Full Name
4. License Level (interactor/viewer/unlicensed)
5. Administrator (system/site/none)
- 326 -
6. Publisher (yes/true/1 or no/false/0)7. Email Address
The file can have fewer columns. For example it can be a simple list with one username perline. When the server is using Active Directory authentication, the Password column shouldbe left blank. Quotesmay be used if a value contains commas. See Import Users from aCSV File on page 70 for other details.Example
tabcmd createusers "users.csv" --license "Interactor" --publisher
Option(short)
Option(long)
Argument Description
--nowait Do not wait for asynchronous jobs tocomplete.
--silent-progress
Do not display progressmessages forasynchronous jobs.
--license Interactor, Viewer, orUnlicensed
Sets the default license level for allusers. This settingmay be overridden bythe value in the CSV file.
--admin-type
System,Site, orNone
Assigns or removes the Admin right to allusers in the CSV file by default. This set-tingmay be overridden by the value inthe CSV file. The default is None for newusers and unchanged for existing users.
--[no-]publisher
Assigns the Publish right to all users inthe CSV file by default. This settingmaybe overridden by the value in the CSVfile. The default is no for new users andunchanged for existing users.
--[no-]complete
Requires that all rows be valid for anychange to succeed. By default, --com-plete option is used.
delete workbook-name or datasource-nameDeletes the given workbook or data source from the server. This command takes the name ofthe workbook or data source as it is on the server, not the file namewhen it was published.
Example
tabcmd delete "Sales_Analysis"
- 327 -
Option(short)
Option(long)
Argument Description
-r --project Projectname
The name of the project containing theworkbook or data source you want todelete. If not specified, the “Default” pro-ject is assumed.
--workbook Workbookname
The name of the workbook you want todelete.
--data-source
Datasourcename
The name of the data source you want todelete.
deletegroup group-nameDeletes the group with the given group-name from the server.
Example
tabcmd deletegroup "Development"
deleteproject project-nameDeletes the project with the given project-name from the server.
Example
tabcmd deleteproject "Designs"
deletesite site-nameDeletes the site with the given site-name from the server.
Example
tabcmd deletesite "Development"
deleteusers filename.csvDeletes the users listed in the given comma separated (CSV) file. The file is a simple list of oneusername per line.
Example
tabcmd deleteusers "users.csv"
- 328 -
Option(short)
Option(long)
Argument Description
--[no-]complete
When set to --complete this optionrequires that all rows be valid for any changeto succeed. If not specified, --complete isused.
editsite site-nameAllows you to change the name of a site or its web folder name. You can also use thiscommand to allow or deny site administrators the ability to add and remove users. If siteadministrators have user management rights, you can specify how many users they can add toa site.
Examples
tabcmd editsite wc_sales --site-name "West Coast Sales"
tabcmd editsite wc_sales --site-id "wsales"
tabcmd editsite wsales --status ACTIVE
tabcmd editsite wsales --user-quota 50
Option(long)
Argument Description
--site-name
Name tochange the siteto
The name of the site that's dislayed.
--site-id
The site ID tochange the siteto
Used in the URL to uniquely identify the site.
--user-quota
Number ofusers
Maximumnumber of users who can bemem-bers of the site.
--[no-]site-mode
Allow or prevent site administrators from addingusers to the site.
--status ACTIVE orSUSPENDED
Activate or suspend a site.
--stor-age-quota
Number of MB InMB, the amount of workbooks, extracts, anddata sources that can be stored on the site.
- 329 -
exportExports a view or workbook from Tableau Server and saves it to a file. Note the following whenyou use this command:
l Permissions: To export, youmust have theExport Image permission. By default, thispermission is Allowed or Inherited for all roles, although permissions can be set perworkbook or view.
l The view, workbook, or data being exported: You specify this using the"workbook/view" string as it appears in the URL for the workbook or view, not usingits “friendly name,” and excluding the hash tag (#) and number at the very end of theURL. For example, to export the Tableau sample view Investment Growth from theFinanceworkbook, you would use the string Finance/InvestmentGrowth, notFinance/Investment Growth, or Finance/InvestmentGrowth#1. Use -t<site_id> if the server is runningmultiple sites and the view or workbook is on a siteother than Default.
To export a workbook, you still include a valid view in the string you use. Using the aboveexample, to export the Financeworkbook, you would use the stringFinance/InvestmentGrowth. Finally, to export a workbook, it must have beenpublished withShow Sheets as Tabs selected in the Tableau Desktop Publish dialogbox.
l The saved file’s format: Your format options depend on what’s being exported. Aworkbook can only be exported as a PDF using the --fullpdf argument. A view canbe exported as a PDF (--pdf), a PNG (--png), or you can export the view’s data as aCSV file (--csv).
l The saved file’s name and location (optional): If you don’t provide a name, it will bederived from the view or workbook name. If you don’t provide a location, the file will besaved to your current working directory. Otherwise, you can specify a full path or onethat’s relative to your current working directory.
l Dashboard web page objects not included in PDF exports: A dashboard canoptionally include a web page object. If you are performing an export to PDF of adashboard that includes a web page object, the web page object won't be included in thePDF.
Clearing the Cache to Use Real-Time DataYou can optionally add the URL parameter ?:refresh=yes to force a fresh data queryinstead of pulling the results from the cache. If you are using tabcmdwith your own scriptingand the refresh URL parameter is being used a great deal, this can have a negative impacton performance. It’s recommended that you use refresh only when real-time data isrequired—for example, on a single dashboard instead of on an entire workbook.
ExamplesViews
tabcmd export "Q1Sales/Sales_Report" --csv -f "Weekly-Report"
- 330 -
tabcmd export -t Sales "Sales/Sales_Analysis" --pdf -f"C:\Tableau_Workbooks\Weekly-Reports"
tabcmd export "Finance/InvestmentGrowth" --png
tabcmd export "Finance/InvestmentGrowth?:refresh=yes" --png
Workbooks
tabcmd export "Q1Sales/Sales_Report" --fullpdf
tabcmd export -t Sales "Sales/Sales_Analysis" --fullpdf --pagesize tabloid -f "C:\Tableau_Workbooks\Weekly-Reports"
Option(short)
Option(long)
Argument Description
-f --filename The name and extension touse for the saved file
Saves the file with thegiven filename.
--csv View only. Export theview’s data in CSVformat.
--pdf View only. Export as aPDF.
--png View only. Export asan image in PNGformat.
--fullpdf Workbook only.Export as a PDF. Theworkbookmust havebeen published withShow Sheets asTabs enabled.
--pagelay-out
landscape, portrait Sets the page ori-entation of the expor-ted PDF. If notspecified, its TableauDesktop setting willbe used.
--pagesize unspecified, letter,legal, note folio,tabloid, ledger,statement, exec-utive, a3, a4, a5,b4, b5, quatro
Sets the page size ofthe exported PDF.Default is letter.
--width Number of pixels Sets the width.
- 331 -
Option(short)
Option(long)
Argument Description
Default is 800 px.--height Number of pixels Sets the height.De-
fault is 600 px.
get urlUsing a URL string as one of its parameters, makes an HTTP GET request of Tableau Server.The result is returned as a file. Note the following when you use this command:
l Permissions: To get a file, youmust have theDownload/Web Save As permission.By default, this permission is allowed or inherited for all roles, although permissions canbe set per workbook or view.
l File extension: The URLmust include a file extension, for example,"/views/Finance/InvestmentGrowth.pdf". The extension (.pdf) determineswhat’s returned. A view can be returned in PDF, PNG, CSV (data only), or XML(information only) format. A Tableau workbook is returned as a TWB if it connects to apublished data source or uses a live connection, or a TWBX if it connects to a dataextract.
To figure out the correct extension, you can use a web browser to navigate to the item onTableau Server and add the file extension to the end of the URL.
When you type the URL for the GET request, exclude the hash tag (#) and number thatappear at the end of the file name. For example, use"/views/Finance/InvestmentGrowth.pdf" instead of"/views/Finance/InvestmentGrowth#3.pdf".
l The saved file’s name and location (optional): The name you use for --filenameshould include the file extension. If you don’t provide a name and file extension, both willbe derived from the URL string. If you don’t provide a location, the file is saved to yourcurrent working directory. Otherwise, you can specify a full path or one that’s relative toyour current working directory.
l PNG size (optional): If the saved file is a PNG, you can specify the size, in pixels, in theURL.
Clearing the Cache to Use Real-Time DataYou can optionally add the URL parameter ?:refresh=yes to force a fresh data queryinstead of pulling the results from the cache. If you are using tabcmdwith your own scripting,using the refresh parameter a great deal can have a negative impact on performance. It'srecommended that you use refresh only when real-time data is required—for example, on asingle dashboard instead of on an entire workbook.
ExamplesViews
- 332 -
tabcmd get "/views/Sales_Analysis/Sales_Report.png" --filename"Weekly-Report.png"
tabcmd get "/views/Finance/InvestmentGrowth.pdf" -f"Q1Growth.pdf"
tabcmd get "/views/Finance/InvestmentGrowth.csv"
tabcmd get "/views/Finance/InvestmentGrowth.png?:size=640,480" -fgrowth.png
tabcmd get "/views/Finance/InvestmentGrowth.png?:refresh=yes" -fgrowth.png
Workbooks
tabcmd get "/workbooks/Sales_Analysis.twb" -f "C:\Tableau_Workbooks\Weekly-Reports.twb"
tabcmd get "/workbooks/Sales.xml"
Other
tabcmd get "/users.xml" --filename "UserList.xml"
Option(short)
Option(long)
Argument Description
-f --file-name
Name to save thefile as
Saves the file with the givenfilename.
listsitesReturns a list of sites to which the logged in user belongs.
Example
tabcmd listsites -u corman -pw P@ssword!
loginLogs in a Tableau Server user. Use the --server, --site, --username, --passwordglobal options to create a session. If you want to log in using the same information you’vealready used to create a session just specify the --password option. The server andusername stored in the cookie will be used.
If the server is using a port other than 80 (the default), you will need to specify the port.
You need the --site (-t) option only if the server is runningmultiple sites and you arelogging in to a site other than the Default site. If you do not provide a password you will be
- 333 -
prompted for one. If the --no-prompt option is specified and no password is provided thecommandwill fail.
Once you log in, the session will continue until it expires on the server or the logout commandis run.
ExampleLogs you in to the Tableau Server running on your local machine:
tabcmd login -s http://localhost -u jsmith -p p@ssw0rd!
Logs you in to the Sales site on sales-server:
tabcmd login -s http://sales-server -t Sales -u administrator -pp@ssw0rd!
tabcmd login -s http://sales-server:8000 -t Sales -uadministrator -p p@ssw0rd!
Logs you in to the Sales site on sales-server using SSL:
tabcmd login -s https://sales-server -t Sales -u administrator -pp@ssw0rd!
Establishes a forward proxy and port for localhost:
tabcmd login --proxy myfwdproxyserver:8888 -s http://localhost -ujsmith -p p@ssW0rd!
Logs you in to the reverse proxy using SSL:
tabcmd login -s https://myreverseproxy -u jsmith -p p@ssW0rd!
Option(short)
Option(long)
Argument Description
-s --server Server URL If you are running the command from an on-premise Tableau Server computer, you can usehttp://localhost. Otherwise, specify the computer’sURL, such as http://bigbox.myco.com orhttp://bigbox.
For TableauOnline specifyhttps://online.tableausoftware.com.
-t --site siteID Include this option if the server hasmultiple sites,and you are logging in to a site other than theDefault site.
The site ID is used in the URL to uniquely identifythe site. For example, a site namedWest CoastSalesmight have a site ID of west-coast-sales.
- 334 -
Option(short)
Option(long)
Argument Description
-u --username
username The username of the user logging in. For TableauOnline, the username is the user’s email address.
-p --password
password Password for the user specified for --username.If you do not provide a password you will beprompted for one.
--password-file
filename.txt Allows the password to be stored in the given filerather than the command line, for increasedsecurity.
-x --proxy Host:Port Use to specify the HTTP proxy server and port forthe tabcmd request.
--no-prompt
Do not prompt for a password. If no password isspecified, the login commandwill fail.
--no-proxy
Do not use an HTTP proxy server.
--[no-]cookie
Saves the session ID on login. Subsequentcommandswill not require a login. Cookies areenabled (--cookie) by default.
--timeoutSECONDS
Number ofseconds
The number of seconds the server should waitbefore processing the login command. Default:30 seconds.
logoutLogs out of the server.
Example
tabcmd logout
publish filename.twb(x), filename.tds(x), or filename.tdePublishes the given workbook (.twb(x)), data source (.tds(x)), or data extract (.tde) to TableauServer. By default, all sheets in the workbook are published without database usernames orpasswords.
If the workbook contains user filters, one of the thumbnail optionsmust be specified.
Example
tabcmd publish "analysis.twbx" -n "Sales_Analysis" --db-username"jsmith" --db-password "p@ssw0rd"
If the file is not in the same directory as tabcmd, include the full path to the file.
Example
- 335 -
tabcmd publish "C:\Tableau Workbooks\analysis.twbx" -n "Sales_Analysis" --db-username "jsmith" --db-password "p@ssw0rd"
Option(short)
Option (long) Argument Description
-n --name Name ofthe work-book ordatasource onthe server
If omitted, the workbook, datasource, or data extract will benamed after filename.
-o --overwrite Overwrites the workbook, datasource, or data extract if it alreadyexists on the server.
-r --project Name of aproject
Publishes the workbook, datasource, or data extract into the spe-cified project. Publishes to the“Default” project if not specified.
--db-user-name
Use this option to publish adatabase usernamewith theworkbook, data source, or dataextract.
--db-pass-word
Use this option to publish a data-base password with the workbook,data source, or data extract.
--save-db-password
Stores the provided database pass-word on the server.
--thumb-nail-user-name
If the workbook contains user fil-ters, the thumbnails will be gen-erated based on what the specifieduser can see. Cannot be specifiedwhen --thumbnail-groupoption is set.
--thumb-nail-group
If the workbook contains user fil-ters the thumbnails will be gen-erated based on what the specifiedgroup can see. Cannot be spe-cified when --thumbnail-user-name option is set.
--tabbed When aworkbookwith tabbedviews is published, each sheetbecomes a tab that viewers canuse to navigate through the work-book. Note that this setting will
- 336 -
Option(short)
Option (long) Argument Description
override any sheet-level security.--append Append the extract file to the exist-
ing data source.--replace Use the extract file to replace the
existing data source.--disable-uploader
Disable the incremental fileuploader.
--disable-tde-com-pression
Stop compressing the extract filebefore it's uploaded.
--restart Restart the file upload.
refreshextracts workbook-name or datasource-namePerforms a full or incremental refresh of extracts belonging to the specified workbook or datasource. This command takes the name of the workbook or data source as it appears on theserver, not the file namewhen it was published. Only an administrator or the owner of theworkbook or data source is allowed to perform this operation.
Examples
tabcmd refreshextracts --datasource sales_ds
tabcmd refreshextracts --workbook "My Workbook"
tabcmd refreshextracts --url SalesAnalysis
Option(short)
Option (long) Argument Description
--incre-mental
Runs the incremental refresh operation.
--syn-chronous
Runs the full refresh operation imme-diately in the foreground.
--workbook Name of aworkbook
The name of the workbook containingextracts to refresh. If the workbook hasspaces in its name, enclose it in quotes.
--data-source
Name of adatasource
The name of the data source containingextracts to refresh.
--project Name of aproject
Use with --workbook or --data-source to identify a workbook or datasource in a project other thanDefault. If
- 337 -
Option(short)
Option (long) Argument Description
not specified, the Default project isassumed.
--url URL nameof a work-book
The name of the workbook as it appearsin the URL. A workbook published as“Sales Analysis” has a URL name of“SalesAnalysis”.
removeusers group-nameRemoves the users listed in the --users argument from the group with the given group-name.
Example
tabcmd removeusers "Development" --users "users.csv"
Option(short)
Option(long)
Argument Description
--users filename.csv Remove the users in the given file from thespecified group. The file should be a simplelist with one username per line.
--[no-]complete
Requires that all rows be valid for anychange to succeed. If not specified --com-plete is used.
runschedule schedule-nameRuns the specified schedule. This command takes the name of the schedule as it is on theserver.
Example
tabcmd runschedule "5AM Sales Refresh"
set settingEnables the specified setting on the server. Details about each setting can be seen on theMaintenance page on the server. Use an exclamationmark in front of the setting name todisable the setting. You can enable or disable the following settings:
l allow_scheduling
l embedded_credentials
l remember_passwords_forever
Example
- 338 -
tabcmd set embedded_credentials
syncgroup group-nameSynchronizes the group with the given group-namewith Active Directory. This command canalso be used to create a new group on the server that is based on an existing Active Directorygroup.
Example
tabcmd syncgroup "Development"
Option(short)
Option (long) Argument Description
--license viewerinteractorunli-
censed
Sets the license level for all users inthe group.
--admin-istrator
systemsite none
Assigns or removes the Admin-istrator right for all users in thegroup. The Administrator user typecan be system, site, or none.Default is none (new users do notget the Administrator right) and exist-ing users are unchanged.
--[no-]pub-lisher
Assigns or removes the Publishright for all users in the group. Ifunspecified, new users are notassigned this right and existingusers are unchanged.
--[no-]com-plete
Requires that all rows be valid forany change to succeed. If unspe-cified, --complete is used.
--silent-pro-gress
Suppresses progressmessages.
versionPrints the version information for the current installation of the tabcmd utility.
Example
tabcmd version
tabadmin
- 339 -
You can perform certain administrative tasks and change Tableau Server configurationsettings using the tabadmin command line tool. It installs with Tableau Server by default andcannot be installed on other computers. For more information, see the topics below:
How to Use tabadmintabadmin allows you to perform administrative tasks from the command line on TableauServer. It installs with Tableau Server by default and cannot be installed on other machines.The first step to using tabadmin is to open a command prompt as an administrator:
Next, navigate to Tableau Server's bin directory by entering the following:
cd "C:\Program Files\Tableau\Tableau Server\8.2\bin"
You're now ready to enter tabadmin commands.
Change Tableau Server's Configuration from the Command LineWhen you enter a command that changes the server's configuration (a tabadmin setcommand for example), you need to follow a sequence of commands:
1. Stop the server before issuing the command.
2. Enter the appropriate command tomake the configuration change.
3. Run tabadmin config to push the change out to all of the server's configuration files.
4. Start Tableau Server again.
Example
Change the server's configuration using the tabadmin set command:
tabadmin stop
- 340 -
tabadmin set [option-name value]
tabadmin config
tabadmin start
Display Command Line HelpUse the tabadmin built-in help to get a quick description of a command.
To display help for all tabadmin commands enter:
tabadmin help commands
To see help for a specific command, enter tabadmin help <command>. For example:
tabadmin help set
tabadmin CommandsHere are the commands that can be used with the tabadmin command line tool:
activate below licenses on page 351administrator on the nextpage passwd on page 352
assetkeys on page 342 restart on page 352autostart on page 343 restore on page 352backup on page 344 set on page 353cleanup on page 344 sitestate on page 354configure on page 345 start on page 354customize on page 346 status on page 355dbpass on page 346 stop on page 356exportsite on page 347 validate on page 356failoverprimary on page349 warmup on page 356
importsite on page 349 ziplogs on page 357importsite_verified onpage 351
activateActivate or return a Tableau Server license online or offline.
- 341 -
ExamplesActivate a license offline:
tabadmin activate --tlf <file.tlf>
Return a license offline:
tabadmin activate --tlr <file.tlr>
Activate a license online:
tabadmin activate --activate <license>
Return a license online:
tabadmin activate --return <license>
Option(short)
Option(long)
Argument Description
--tlf FILE For offline activation. If you are offline during Setup,you are prompted to save a .tlq file, which yousubmit to Tableau.Tableau sends you a .tlf file. Youuse this .tlf file to activate Tableau Server.
--tlr FILE For offline deactivation. The file you use as the argu-ment is the .tlr file that you receive from Tableau.
--activ-ate
Activate the specified license.
--return Return the specified license.
See Also
Activate Tableau Offline on page 6
administratorGrants or removes the system administrator capability to the named user. This command doesnot apply to site administrators.
ExamplesRemove the system administrator capability from user hwilson:
tabadmin administrator hwilson false
Give the system administrator capability to user jsmith:
- 342 -
tabadmin administrator jsmith true
assetkeysCreates a new key to encrypt sensitive information, such as credentials for external databases,stored within the Tableau repository, which is a PostgreSQL database that Tableau Serveruses internally. The key you create with this command can contain either a passphrase thatyou specify or one that's randomly generated.
If you specify your key's passphrase, it's a best practice for it to be at least eight characterslong. You should also take character sets into consideration. A strong passphrase shouldcontain characters from at least three of the following character sets:
l Lowercase a-z
l Uppercase A-Z
l Digits 0-9
l Non-alphabetic characters
The new key is encrypted and stored in the following key file: asset_keys.yml(ProgramData\Tableau\Tableau Server\data\tabsvc\config). If the key file is lost or corrupted,you can use the assetkeys --validate command to recreate it.
If you use the assetkeys command then later create and restore a backup file (.tsbak), you willneed to run the tabadmin assetkeys --validate command after restoring the backupfile. By design, backup files do not contain custom encryption keys—even though some datamay be encrypted with them. This protects the encrypted values in case the backup file fallsinto the wrong hands.When you run tabadmin assetkeys --validate after a backuprestore, you are prompted to enter the key's passphrase.
ExamplesHave Tableau Server generate a key and passphrase for you:
tabadmin assetkeys --auto_create
Generate a key using a passphrase that you specify. You are prompted to enter a passphrase,which will not be displayed as you type:
tabadmin assetkeys --create
Use the contents of a file as the passphrase:
tabadmin assetkeys --create_from_file C:\test\key\password.txt
Confirm that the key file asset_keys.yml in ProgramData\Tableau\TableauServer\data\tabsvc\config is valid and consistent with themetadata in the Tableau Repository:
tabadmin assetkeys --validate
- 343 -
Recreate the file asset_keys.ymlwhich is now corrupted or missing fromProgramData\Tableau\Tableau Server\data\tabsvc\config:
tabadmin assetkeys --validate
Youwill be prompted for the passphrase.
Option(short)
Option (long) Argument Description
--auto_cre-ate
[length] Generates a random passphrase to generatethe key. Takes an optional argument for thelength of the passphrase. You should recordthe passphrase and keep it in a safe place, as itwill be required by --validate if assetkeys.yml islost or corrupted.
--create PASSPHRASE Creates the passphrase of your choice to beused as the key. Your passphrase should be atleast 10 characters long and not based onwords found in the dictionary.
--create_from_file
FILE Generates a key using the contents of a file thatyou provide as the passphrase.
--validate Confirms that all asset keys being used intern-ally by Tableau Server are up-to-date. If youlose the asset_keys.yml file (for example, dueto file corruption), you can use the --val-idate option to recreate it. To successfullyrecreate the key file, youmust supply the pass-phrase used to generate any keys currently inuse.
See AlsoSecurity on page 218
autostartBy default, Tableau Server starts at system start-up time. You can use this command tochange that default behavior. If autostart is set to off, you will need to start TableauServer either using tabadmin start or the Start menu.
ExampleDisplay Tableau Server's auto-start status:
tabadmin autostart
Start Tableau Server when the operating system starts:
- 344 -
tabadmin autostart on
Do not start Tableau Server when the operating system starts:
tabadmin autostart off
backupCreate a backup of the datamanaged by Tableau Server. This data includes Tableau's ownPostgreSQL database, which contains workbook and user metadata, data extract (.tde) files,and configuration data. You do not need to stop Tableau Server before you create a backupfile.
ExamplesCreate a backup file in Tableau Server's bin directory named tabserv.tsbak:
tabadmin backup tabserv.tsbak
Create a backup file in the C:\backups\tableau folder named tabserv.tsbak:
tabadmin backup C:\backups\tableau\tabserv.tsbak
Append the current date to the backup file name and put temporary files created during thebackup process in C:\mytemp\tableau. The backup file tabserv.tsbakwill be created in theTableau Server bin directory:
tabadmin backup tabserv.tsbak -d -t C:\mytemp\tableau
Option(short)
Option(long)
Argument Description
-d --date Appends the current date to the backup file name-u --userdir Places the backup file in the Pro-
gramData\Tableau\Tableau Server folder.-t --tempdir PATH Location for temporary files created during the backup
process.
See Also
Back Up the Tableau Data on page 366
cleanupReduces the disk space consumed by Tableau Server. Running tabadmin cleanupremoves log files, temporary files, and select rows in Tableau Server's PostgreSQL database.
- 345 -
The effect of the cleanup command depends on whether the server is running or stopped. Formore information, seeRemove Unneeded Files on page 368ExamplesRemove log files, temporary files, and HTTP request entries in the PostgreSQL database:
tabadmin cleanup
Remove log files and temporary files (leave HTTP request entries in the database untouched):
tabadmin cleanup --restart
Option(short)
Option(long)
Argument Description
-r --restart
Stops Tableau Server, runs the cleanupcommand, and starts the server again.
See Also
Remove Unneeded Files on page 368
configureUpdates Tableau Server's configuration by forcing an update to all the files inProgramData\Tableau\Tableau Server\data\tabsvc\<area>. This update includes refreshingthemaster service configuration file, workgroup.yml (ProgramData\Tableau\TableauServer\data\tabsvc\config). When youmake a configuration change, it's a best practice to runtabadmin configure (or tabadmin config) to ensure that all files affecting theserver’s configuration are completely updated.
Examples
tabadmin configure
tabadmin config
See Also
Reconfigure the Server on page 22set on page 353tabadmin set options on page 358
- 346 -
customizeCustomize the name and logo that are used by Tableau Server. Note that even if you use thiscommand, the copyright information at the bottom of every server page will list Tableau'scopyright information.
ExampleChange the product name fromTableau Server to MyCo Server:
tabadmin customize name "MyCo Server"
Change the default logo to your own, "large size" logo (up to 160 x 160 px but not smaller than32 x 32 px):
tabadmin customize logo "C:\My Pictures\example.png"
Change the default logo to your own "small size" logo (32 x 32 px or smaller):
tabadmin customize smalllogo "C:\My Pictures\example_small.png"
Customize the default product name that's used in places like the Tableau Server sign-in page:
tabadmin customize name -d
Option(short)
Option(long)
Argument Description
-d --default Resets the name or logo to its default value.
See Also
Change the Name or Logo on page 152
dbpassEnables external access to Tableau's PostgreSQL database (the repository). After you use thedbpass command to allow access to the database, you can connect to and query it usingTableau Desktop to create your own administrative views.
tabadmin dbpass [--disable] [--username <username>] [password]
Note: The --username option is valid starting with Tableau Server 8.2.5. In earlierversions dbpass only enabled the "tableau" user and you could not specify the user.8.2.5 added a second user called "readonly" and introduced the ability to specify the useryou are enabling access for.
Examples
- 347 -
Enable access for the tableau user and set the password to p@ssword:
tabadmin dbpass p@ssword
Enable access for the readonly user and set the password to p@ssword:
tabadmin dbpass --username readonly p@ssword
Disable external access for the default (tableau) user:
tabadmin dbpass --disable
or
tabadmin dbpass --disable --username tableau
Disable external access for the readonly user:
tabadmin dbpass --disable --username readonly
Option(long)
Argument Description
--disable Disable external access to Tableau's PostgreSQL database forthe default remote user (tableau) or, starting in 8.2.5, if a username is specified, disable remote access for that user.
--username tableau orreadonly
Change the password for the specified user, or, if used with the --disable option, disable access for the specified user. Options forusers are tableau and readonly. This option is valid inTableau Server 8.2.5 or higher.
passwordprovidedby user
Enable remote access to Tableau's PostgreSQL database forthe default remote user (tableau) or, starting in 8.2.5, if a username is specified, enable access for that user with the givenpassword.
See Also
Create Custom Administrative Views on page 163Enabling External Access to the Tableau Server Database on page 164
exportsiteExports a Tableau Server site, including its users, workbooks, projects, extracts, and dataconnections, and places it in a file with a .zip file extension. You can then use the exported sitefile to provision a new site by using the importsite on page 349 and importsite_verified on page 351 commands.
You don't need to stop Tableau Server before you use the exportsite command. TableauServer will lock the site being exported during the export process.
- 348 -
Examplestabadmin exportsite <site ID> --file <PATH>
ortabadmin exportsite <site ID> --file <FILE>
Export the site whose site ID is finance to a file named finance_export.zip and place it inProgramFiles\Tableau\Tableau Server\8.2\bin:tabadmin exportsite finance --file finance_export
Export the Default site. The site ID for the Default site is "" (double quotes, no space).tabadmin exportsite "" --file finance_export
If you are usingWindowsPowerShell to run the command, enclose the double quotesfor the Default site within single quotes ('""'). For example: tabadminexportsite '""' --file finance_export
Export the Default site to a file named finance_export.zip and place it in C:\temp\exportedsites instead of in the Tableau Server bin directory. Because the path contains a space, it'scontained by quotes:tabadmin exportsite "" --file "C:\temp\exported sites\finance_export"
Export the site whose site ID is finance, name the export site file financesite.zip, place the filein C:\sites\exported, and write temporary run-time files to C:\temp_files:tabadmin exportsite finance --file C:\sites\exported\financesite--tempdir C:\temp_files
Option(short)
Option (long) Argument Description
--file FILE or
PATH
The name or name and location (path) of the expor-ted site file to be created. If you don't specify a path,Tableau Server's bin directory is the assumed loc-ation (ProgramFiles\Tableau\Tableau Server-\8.2\bin).
--tempdir The location of temporary files created duringexport. Use this option if you don't have writeaccess to the Tableau Server installation directory.This option does not determine where the exportsite file is created.
See Also
Import or Export a Site on page 123
- 349 -
failoverprimaryIdentify a second installation of the primary Tableau Server as the backup primary, or if theprimary has failed, identify the backup primary as the new primary and the former primary asthe new backup.
Example
tabadmin failoverprimary --primary <computer name(s) or IPv4address(es)>
Option(short)
Option (long) Argument Description
--primary Computer name(s)or IPv4 address(es)
The Tableau Server machine that's actingas the cluster's primary.
See Also
Understanding High Availability on page 45Configure for Failover and Multiple Gateways on page 50Configure a Backup Primary on page 60
importsiteThe importsite command is the first of two commands you use to import a site into TableauServer. To run this command, you need the following:
l An exported site file. Tableau Server administrators create this file using theexportsite on page 347 command. If you have a site on TableauOnline and youwant to import it into your own, on-premise installation of Tableau Server request anexported site file from Tableau Customer Support.
l The Site ID for the target site. The target site is the Tableau Server site into whichyou are importing. The target site must already exist when you run the importsitecommand, you can't create it as part of the command. The site ID for Tableau Server'sDefault site is ""(double quotes, no space).
The contents of the site you import will replace the contents of the target site. Forexample, if your target site has a workbook namedMyDashboard.twbx and the siteyou are importing does not have this workbook, the import processwill removeMyDashboard.twbx from the target site.
Running the importsite command creates a temporary directory containing CSV files thatshow how the exported site's assets (users, workbooks, projects, extracts, and data sources)will bemapped once it's fully imported. User details, such as authentication, are important toverify. Use a text editor or Microsoft Excel to open themapping files andmake any changes.Any entries with ??? (questionmarks) represent mappings that couldn't be handled andmust
- 350 -
be edited. After you verify themappings, finish the import process using the importsite_verified on the next page command.
Examplestabadmin importsite <site ID> --file <PATH>
ortabadmin importsite <site ID> --file <FILE>
Import the file sales_site.zip located in C:\tableau\exported to a site whose site ID iswsales:tabadmin importsite wsales --file C:\tableau\exported\sales_site.zip
Import the file sales_site.zip, which is located in located in C:\ProgramFiles\Tableau\TableauServer\8.2\bin, to the Default site. The site ID for the Default site is "" (double quotes, nospace).tabadmin importsite "" --file sales_site.zip
Themapping files for you to verify are placed in ProgramData\Tableau\TableauServer\data\tabsvc\temp\import_<site ID>_<datetime>\mappings. To specify a differentdirectory, use the --tempdir option.
Place the files to be verified in C:\temp\site_to_import:
tabadmin importsite wsales --file "C:\tableau\exported\sales_site.zip" --tempdir "C:\temp\site_to_import"
Skip the verification step (not recommended):tabadmin importsite wsales --file "C:\tableau\exported\sales_site.zip" -no-verify
Option(short)
Option(long)
Argument Description
--file PATH The name and location of the exported site file you areimporting. If you don't specify a path, Tableau Server'sbin directory is the assumed location (ProgramFiles\T-ableau\Tableau Server\8.2\bin).
--no-verify
Skips the verification step and imports the exported sitefile directly to its new location in your Tableau Serverinstallation. You do not also need to use theimportsite_verified command.
--tempdir PATH The directory where you will verify that the site fileshave the correct mappings. If you don't specify thisoption, files are placed in a directory under Pro-gramData\Tableau\Tableau Server\data\tabsvc\temp.
See Also
Import or Export a Site on page 123
- 351 -
importsite_verifiedThe second command used to import a site to Tableau Server. Before you can useimportsite_verified, youmust first use importsite on page 349.
The importsite_verified command reads from a directory containing CSV files thatyou have verified, and imports a new site into Tableau Server based on how the site's assetsaremapped in the CSV files. The site that receives the import (the target site) must alreadyexist on Tableau Server.
During the import process, Tableau Server locks the site receiving the import.
Examplestabadmin importsite_verified <target site ID> --importjobdir<PATH>
Import files from the directory C:\temp\site_to_import to the site whose site ID is esale:tabadmin importsite_verified esales --importjobdir C:\temp\site_to_import
Option(short)
Option (long) Argument Description
--import-jobdir
PATH The directory containing CSV files whosemap-pings you have verified.
See Also
Import or Export a Site on page 123
licensesDisplay license information for Tableau Server.
Examples
tabadmin licenses
tabadmin licenses -p
Option(short)
Option (long) Argument Description
-p --processor_cores
Display the physical core count for the currentmachine.
- 352 -
passwdResets the password for a Tableau Server account. After typing the command, you areprompted to enter a new password for the user.
You can only use this command if Tableau Server's user authentication is set to LocalAuthentication.When authentication is set to Active Directory, passwords are handled byActive Directory, not Tableau Server.
Examples
tabadmin passwd <username>
Reset the password for server user jsmith:
tabadmin passwd jsmith
See Also
General on page 8
restartStops and starts all Tableau Server processes.
Example
tabadmin restart
restoreRestores a Tableau Server backup file (.tsbak) to a Tableau Server installation. When yourestore a .tsbak file, the contents of the Tableau PostgreSQL database, data extracts, andconfiguration files are overwritten with the content in the backup file. Using the --no-configoption restores everything but the server's configuration.
ExamplesRestore a file named tabserv.tsbak located in C:\mybackups and then restart the server:
tabadmin restore C:\mybackups\tabserv.tsbak --restart
Restore a file named tabserv.tsbak located in the Tableau Server bin directory and thenrestart the server:
tabadmin restore tabserv.tsbak --restart
- 353 -
Restore a file named tabserv.tsbak located in C:\mybackups, retaining everything but theserver's configuration, but don't restart the server:
tabadmin restore --no-config C:\mybackups\tabserv.tsbak
Option(short)
Option (long) Argument Description
--no-con-fig
Restore the Tableau Server backup file including thedata but excluding the server's configuration.
--restart Restart the service when the restore process hascompleted.
See Also
Restore from a Backup on page 367Recover Extracts from a Backup on page 368
setAllows you to change the value of Tableau Server configuration options. If the parameteryou're setting begins with a hyphen, enclose the parameter's value in both double- and single-quotes.
Examples
tabadmin set [option-name value]
Set the backgrounder query limit to 2.5 hours (9000 seconds):
tabadmin set backgrounder.querylimit 9000
Set the wgserver virtual memory parameter to -Xmx512m:
tabadmin set wgserver.vmopts "'-Xmx512m'"
Set the wgserver virtual memory parameter to a range of -Xmx512m -Xss2048k:
tabadmin set wgserver.vmopts "'-Xmx512m -Xss2048k'"
Option(short)
Option(long)
Argument Description
-d --default
Reset the parameter to its default value.
See Also
tabadmin set options on page 358
- 354 -
sitestateUse to activate a site that was locked because of a site import failure, or to suspend a site.When a site is suspended, the only Tableau Server user who can access it is the systemadministrator.
Examplestabadmin sitestate <site ID> --status <active|suspended>
Unlock, or activate, a site whose site ID iswsales:
tabadmin sitestate wsales --status active
Option(short)
Option(long)
Argument Description
--status
active
orsuspended
Either activates or suspends the site specified by <siteID>.
startStarts all Tableau Server processes. To use tabadmin start:
1. Open a command prompt as an administrator:
2. Type the following:
- 355 -
cd "C:\Program Files\Tableau\Tableau Server\8.2\bin"
3. Type the following to start the server:
tabadmin start
Examples
tabadmin start
tabadmin start --wait 1200
Option(short)
Option(long)
Argument Description
--wait number ofseconds
Number of seconds after starting after which TableauServer is ready to accept client requests. The default is600 seconds.
statusTells you whether or not Tableau Server is running and, if you use the --verbose option,gives you details on individual server process status, including whether or not a process is upand running and which port it's using. The tabadmin status command obtains itsinformation by connecting to theWindowsService tabsvc.exe, which in turn queries thetabspawn executables for each process. Because of this, it can sometimes display differentinformation for the server processes than the Status table on theMaintenance page, whichqueries the processes directly.
Examples
tabadmin status
tabadmin status --verbose
Option(short)
Option(long)
Argument Description
-v --verbose Returns a list of all the Tableau Server processes, theirport numbers and status.
See Also
Maintenance Settings on page 138Tableau Server Processes on page 372
- 356 -
stopStops all Tableau Server processes. To use tabadmin stop:
1. Open a command prompt as an administrator:
2. Type the following:
cd "C:\Program Files\Tableau\Tableau Server\8.2\bin"
3. Type the following to stop the server:
tabadmin stop
validateConfirmswhether your Tableau Server environment meets theminimum requirements forrunning the 64-bit version of Tableau Server. If you are currently running the 32-bit version ofTableau Server, running this command before you upgrade to the 64-bit version can help youconfirmwhether your current hardware, disk space, and RAMare sufficient.
Example
tabadmin validate
warmupCauses every VizQL server process to load the vizql DLL file, resulting in faster load timeswhen server users first load views. Administrators can run this command, or script it to be run,
- 357 -
after a Tableau Server restart.
Example
tabadmin warmup
ziplogsCreates an archive (.zip) containing Tableau Server log files, without removing the log filesthemselves. If you are running a Tableau Server cluster, log files fromworker servers areincluded in the archive that's created.
ExamplesCreate an archive in the Tableau Server bin directory named logs.zip:
tabadmin ziplogs
Create an archive in the Tableau Server bin directory namedmylogs.zip:
tabadmin ziplogs mylogs.zip
Create an archive in the Tableau Server bin directory namedmylogs.zip that includes logsdated January 31, 2014 up to the present, excluding earlier logs:
tabadmin ziplogs -d 01/31/2014 mylogs.zip
Option(short)
Option (long) Argument Description
-n --with-netstat-info
Include information about the server envir-onment in the .zip file.
-p --with-post-gresql-data
Include data from Tableau Server's Post-greSQL database.
-l --with-latest-dump
Limit the included log files to only themostrecent ones to help reduce file size. Bydefault, the 10most recent log files areincluded.
-f --force Overwrites the existing log file of the samename.
-d --minimumdate [mm/dd/yyyy] Log files with this date, up to the present,are included in the .zip file. Logs datedearlier are excluded from the file. If not spe-cified, up to seven daysworth of data isincluded.
-a --all Include all log files in the .zip file. Data fromTableau Server's PostgreSQL database is
- 358 -
Option(short)
Option (long) Argument Description
still excluded.
See Also
Work with Log Files on page 371Archive Logs on Command Line (tabadmin) on page 378
tabadmin set optionsUse the table below to learnmore about Tableau Server options you can configure using theset on page 353 command. See TCP/IP Ports on page 313 for a complete list of ports.
Option DefaultValue
Description
api.server.enabled false Allows access to theREST API on page 441.By default, this functionality is disabled.
auditing.enabled true Allows access to the PostgreSQL (TableauServer's own database) historical auditingtables. SeeCreate Custom AdministrativeViews on page 163 for details.
backgrounder.querylimit 7200 Longest allowable time for completing an extractrefresh, in seconds (7200 seconds = 2 hours).
backgrounder.reset_sched-ules_on_startup
true Controls when to run background tasks thatwere scheduled to run at a time when the serverwas stopped.When set to true (the default),tasks are run at their next scheduled time.Whenset to false, all tasks that were scheduled torun when the server was stopped are run, sim-ultaneously, at server startup, including timeswhen the Tableau Server backup file (.tsbak) isrestored.
dataengine.port 27042 Port that the data engine runs on.
dataserver.port 9700 Port that the data server runs on.
gateway.public.host Name of themachine
The name (URL) of the server, used for external
- 359 -
Option DefaultValue
Description
access to Tableau Server. If Tableau Server isconfigured to work with a proxy server orexternal load balancer, it is the name entered ina browser address bar to reachTableau Server.For example, if Tableau Server is reached byentering tableau.example.com, the namefor gateway.public.host is tableau-.example.com.
gateway.public.port 80 (443 ifSSL)
Applies to proxy server environments only. Theexternal port the proxy server listens on.
gateway.timeout 1800 Longest amount of time, in seconds, that thegatewaywill wait for certain events before failinga request (1800 seconds = 30minutes).
gateway.trusted IP address ofproxy servermachine
Applies to proxy server environments only. TheIP address(es) or host name(s) of the proxyserver.
gateway.trusted_hosts Alternatename(s) ofproxy server
Applies to proxy server environments only. Anyalternate host name(s) for the proxy server.
java.heap.size 128m Size of heap for Tomcat (repository and solr).This generally does not need to change excepton advice from Tableau.
pgsql.port 8060 Port that PostgreSQL listens on.
rsync.timeout 600 Longest allowable time, in seconds, for com-pleting file synchronization (600 seconds = 10minutes). File synchronization occurs as part ofconfiguring high availability, or moving the dataengine and repository processes.
server.log.level info The logging level for logswritten toProgramData\Tableau\TableauServer\data\tabsvc\logs\vizqlserver\Logs\*.txt.
Set to debug for more information.When set todebug, logging is set to pre-8.2 verbosity.Debug-level can significantly impactperformance and you should only use it whendirected to do so by Tableau Support. SeeChange Logging Levels on page 385 for
- 360 -
Option DefaultValue
Description
more information.
service.jmx_enabled false Setting to true enables JMX ports for optionalmonitoring and troubleshooting. SeeEnablethe JMX Ports on page 317 for details.
service.max_procs # of pro-cesses
Maximumnumber of server processes.
service.port_remap-ping.enabled
true Determineswhether or not Tableau Server willattempt to dynamically remap ports when thedefault or configured ports are unavailable. Set-ting to false disables dynamic port remap-ping. See TCP/IP Ports on page 313 for moreinformation.
solr.rebuild_index_timeout 3600 When Tableau Server is upgraded or when a .ts-bak file is restored, the background task rebuildsthe search index. This setting controls thetimeout setting for that task (3600 seconds = 60minutes).
subscriptions.enabled false Controls whether subscriptions are configurablesystem-wide. SeeManage Subscriptions onpage 104.
subscriptions.timeout 1800 Number of seconds after which the backgroundprocess handling a subscription times out.
solr.port 8080 Port that solr listens on. Thismust be the samevalue as tomcat.http.port.
tomcat.http.port 8080 Port that Tomcat runs on.
tomcat.https.port 8443 SSL port for Tomcat (unused).
tomcat.server.port 8085 Port that tomcat listens on for shutdownmes-sages.
vizqlserver.browser.render true Views under the threshold set by vizqlserv-er.browser.render_threshold orvizqlserver.browser.render_threshold_mobile are rendered by the cli-ent web browser instead of by the server. SeeAbout Client-Side Rendering on page 235for details.
vizqlserv-er.browser.render_
100 The default value (100) represents a high levelof complexity for a view displayed on a PC. Com-
- 361 -
Option DefaultValue
Description
threshold plexity factors include number of marks, head-ers, reference lines, and annotations. Views thatexceed this level of complexity are rendered bythe server instead of in the PC's web browser.
vizqlserv-er.browser.render_threshold_mobile
20 The default value (20) represents a high level ofcomplexity for a view displayed on a tablet. Com-plexity factors include number of marks, head-ers, reference lines, and annotations. Views thatexceed this level of complexity are rendered bythe server instead of in the tablet's web browser.
vizqlserver.log.level info The logging level for vizqlserver javacompenents. Logs are written toProgramData\Tableau\TableauServer\data\tabsvc\logs\vizqlserver\*.log.
Set to debug for more information. Debug-levelcan significantly impact performance and youshould only use it when directed to do so byTableau Support. SeeChange LoggingLevels on page 385 for more information.
vizqlserver.port 9100 Base port for the VizQL servers.
vizqlserver.protect_ses-sions
true When set to true (the default), prevents VizQLsessions from being reused after the originaluser signs out.
vizqlserver.querylimit 1800 Longest allowable time for updating a view, inseconds.
vizqlserver.rserve.host Specifies an Rserve host. This setting, and thethree settings immediately below, supports Rfunctionality in workbooks.R is an open sourcesoftware programming language and a softwareenvironment for statistical computing and graph-ics. In Tableau Desktop, you can use a set offour functions to passR expressions to anRserve server and obtain a result. If you uploada workbook that uses any of these functions,you should configure Tableau Server for anRserve connection, by configuring this optionand the three following. Otherwise, anywork-sheets that use R functionality will be unavail-
- 362 -
Option DefaultValue
Description
able. See R Connection in the Tableau Desktophelp for further details.
vizqlserver.rserve.port 6311 Specifies an Rserve port. This setting supportsR functionality in workbooks.
vizqlserv-er.rserve.username
Specifies an Rserve username. This setting sup-ports R functionality in workbooks. Not allRserve hosts require a username and pass-word.
vizqlserv-er.rserve.password
Specifies an Rserve password. This setting sup-ports R functionality in workbooks. Not allRserve hosts require a username and pass-word.
vizqlserv-er.session.expiry.minimum
5 Number of minutes of idle time after which aVizQL session is eligible to be discarded if theVizQL process starts to run out of memory.
vizqlserv-er.session.expiry.timeout
30 Number of minutes of idle time after which aVizQL session is discarded.
vizqlserver.showdownload true Controls the display of the Download buttonabove views.
vizqlserver.showshare true Controls the display of the Share button aboveviews.
vizqlserv-er.trustedticket.log_level
info The logging level for trusted authentication,written toProgramData\Tableau\TableauServer\data\tabsvc\logs\vizqlserver\vizql-*.log.
Set to debug for more information. Debug-levelcan significantly impact performance and youshould only use it when directed to do so byTableau Support. SeeChange LoggingLevels on page 385 for more information.
vizqlserv-er.trustedticket.token_length
24 Determines the number of characters in eachtrusted ticket. The default setting of 24 char-acters provides 144 bits of randomness. Thevalue can be set to any integer between 9 and255, inclusive.
vizqlserv- false When set to true, tickets are 9 digits long (as in
- 363 -
Option DefaultValue
Description
er.trustedticket.use_deprecated_9digit_token
version 8.0 and earlier) and the settingvizqlserver.trustedticket.token_length is ignored.
vizqlserver.url_scheme_whitelist
Adds to the protocols to whitelist when usingURL actions on views and dashboards. http,https, gopher, news, ftp, and mailto arewhitelisted by default.
wgserver.audit_history_expiration_days
183 Number of days after which historical eventsrecords are removed from the PostgreSQL data-base (Tableau Server's own database). SeeCreate Custom Administrative Views onpage 163 for details.
wgserv-er.authentication.desktop_nosaml
Controls whether or not Tableau Desktop usesSAML for authentication. Use this option whenyour IdP does not use forms-based authen-tication. Valid options are true and false. Bydefault this is not set so the behavior is equi-valent to setting it to false. Set this to true to dis-able SAML authentication for Tableau Desktop.
wgserver.change_own-er.enabled
true Controls whether the ownership of a workbook,data source or project can be changed. Otheroptions include "false" and "adminonly". SeeManage Ownership on page 214 for details.
wgserver.clickjack_defense.enabled
false When set to true, helps prevents amaliciousperson from "clickjacking" a Tableau Serveruser. In a clickjack attack, the target page is dis-played transparently over a second page, andthe attacker gets the user to click or enter inform-ation in the target page while the user thinks heor she is interacting with the second page.
Enabling clickjack protection can affect thebehavior of content served by Tableau Server.For more information, see Clickjack Protectionin Tableau Server in the Tableau KnowledgeBase.
wgserver.domain.fqdn value of%USERDOM-AIN%
The fully qualified domain name of the Active Dir-ectory server to use.
- 364 -
Option DefaultValue
Description
wgserver.log.level info The logging level for wgserver javacomponents. Logs are written toProgramData\Tableau\TableauServer\data\tabsvc\logs\wgserver\*.log.
Set to debug for more information. Debug-levelcan significantly impact performance and youshould only use it when directed to do so byTableau Support. SeeChange LoggingLevels on page 385 for more information.
wgserver.password_auto-complete.enabled
false Controls whether web browsers are allowed toautomatically complete password fields.
wgserv-er.sam-l.idpattribute.username
username Specifies the attribute used by the IdP for SAMLauthentication. The default is username.
wgserv-er.saml.maxassertiontime
3000 Specifies themaximumnumber of seconds,from creation, that an assertion is usable.
wgserv-er.sam-l.maxauthenticationage
7200 Specifies themaximumnumber of secondsallowed between user's authentication and pro-cessing of the AuthNResponsemessage.
wgserv-er.saml.responseskew
180 Sets themaximumnumber of secondsdifference between Tableau Server time andthe time of the assertion creation (based on theIdP server time) that still allows themessage tobe processed.
wgserver.session.idle_limit 240 The number of minutes of idle time before asign-in to the web application times out.
workerX.gateway.port 80 (443 ifSSL)
External port that Apache listens on for work-erX. worker0.gateway.port is Tableau Server’sexternal port. In a distributed environment, work-er0 is the primary Tableau Server.
workerX.vizqlserver.procs # of pro-cesses
Number of VizQL servers.
workerX.vizqlserver.port 9100 Base port for the vizQL server on workerX.
workerX.wgserver.port 8000 Base port for the web application server onworkerX.
workerX.wgserver.procs # of pro- Number of web application server processes.
- 365 -
Option DefaultValue
Description
cessors
Restore a Setting to its Default ValueYou can restore the default value for a Tableau Server configuration setting by doing thefollowing:
1. Stop the server.
2. Still in the bin directory, restore the default value for a particular setting by typing thefollowing:
tabadmin set option-name --default
For example, to set the tabadmin vizqlserver.session.expiry.timeout option back to itsdefault value of 30minutes, you would type the following:
tabadmin set vizqlserver.session.expiry.timeout --default
Alternatively, you can use the shorter -d command. For example:
tabadmin set vizqlserver.querylimit -d
3. Next, run the configure command:
tabadmin configure
4. Start the server.
- 366 -
Database MaintenanceA Tableau Server administrator should perform regular databasemaintenance, monitor diskusage on the server, and clean up unnecessary files to free up space on the server. Takingthese steps can help ensure that Tableau Server runswith maximumefficiency.
You can use the tabadmin command line tool to back up and restore your Tableau data, and toclean up unnecessary log and temporary files. Tableau data includes Tableau Server's ownPostgreSQL database, which storesworkbook and user metadata, data extract (.tde) files, andserver configuration data. Tableau Server log files capture activity and can help you diagnoseproblems. Logs are written to folders on the server and you can archive and remove them tosave disk space. Use the commands described in the topics below, along with the built-inWindows task scheduler to automate backing up data and cleaning up unnecessary files.
Back Up the Tableau DataIt is important to back up your Tableau data so you can restore published views and otherinformation in the case of a system failure. The datamanaged by Tableau Server consists ofTableau's own PostgreSQL database, which contains workbook and user metadata, dataextract (.tde) files, and configuration data. When you create a backup, all these things areplaced in a single file with a .tsbak extension. If you are running a distributed installation ofTableau Server this step is performed on the primary, even if the data engine, which handlesthe .tde files, is on a worker. So that it can be an effective backup for you, be sure to store the.tsbak on a computer that's separate from your Tableau Server host.
You can create a .tsbak file using the procedure below. Tableau Uninstall, which is the first stepto upgrading to a new version, also automatically creates a .tsbak file. This same .tsbak file isused to automaticallymigrate your data to your newer version.
Running the backup command also removes Tableau Server log files older than sevendays aswell as some of the information displayed in certain Tableau ServerAdministrative Views on page 155.
1. Open a command prompt as an administrator and type the following:
cd "C:\Program Files\Tableau\Tableau Server\8.2\bin"
2. Create a backup file by typing tabadmin backup <filename>, where<filename> is the name or location and name of your backup file. Starting with version8.1, there is no need to stop the server before you create the backup. For example:tabadmin backup tabserver
ortabadmin backup C:\backups\tableau\tabserver
- 367 -
You can also optionally use -d to append the current date to the file name and -t,followed by a path, to specify a location for temporary files that are created during thebackup process. For example:tabadmin backup tabserver -d -t C:\mytemp\tableau
In the above example, the backup file tabserver.tsbakwill be created in theTableau Server bin directory (C:\Program Files\Tableau\TableauServer\8.2\bin) not in C:\mytemp\tableau.
Restore from a BackupWhen you restore, the contents of the Tableau PostgreSQL database, data extracts, andconfiguration files are overwritten with the content in the backup file (.tsbak). If you are runninga distributed installation of Tableau Server, this step is performed on the primary.
To restore from a database backup file:
1. Stop the server by typing:
tabadmin stop
2. Restore the database from a backup file by typing:
tabadmin restore <filename>
In the above line, replace <filename> with the name of the backup file you want torestore from.
To restore only the data and no configuration settings, type the following instead:
tabadmin restore --no-config <filename>
3. Restart the server by typing:
tabadmin start
4. If you ran the tabadmin assetkeys command at any time before you created thebackup file that you're now restoring, run the following command:
tabadmin assetkeys --validate
You'll be prompted to enter the passphrase needed to re-create the custom encryptionkeys in use in the backup file.
When you restore a .tsbak file, Tableau Server automatically creates a copy of its current datafolder, names it tabsvc.bak-*, and places it in ProgramData\Tableau\TableauServer\data. This folder is an emergency backup of Tableau Server data which TableauSupport may be able to use in case something goeswrong during backup restoration.
- 368 -
Once a restoration is complete, it's safe to remove any tabsvc.bak-* folders fromProgramData\Tableau\Tableau Server\data to free additional disk space. InTableau Server clusters, tabsvc.bak-* folders are created on eachmachine runningTableau Server.
Do not remove the tabsvc folder, which is also located underProgramData\Tableau\Tableau Server\data. It contains Tableau Serverdata. Remove only the tabsvc.bak-* folders.
Recover Extracts from a BackupThe file uninstall-<version>.tsbak (for example, uninstall-8.1.tsbak) is created as part of theuninstall process. After you upgrade to version 8.2, you can use this file to restore dataextracts—for example, if youmistakenly deleted the dataengine folder during the upgrade. Touse uninstall-<version>.tsbak to restore data extracts:
1. Stop the server.
2. Fromwithin your version 8.2 Tableau Server bin directory, type the following:
WindowsServer 2012,WindowsServer 2008,WindowsVista, Windows 7,Windows 8:tabadmin restore \ProgramData\Tableau\TableauServer\uninstall-8.1.tsbak
32-bit Tableau Server installed on 64-bit WindowsServer 2003: tabadmin restore\Program Files (x86)\Tableau\Tableau Server\uninstall-
8.1.tsbak
32-bit Tableau Server installed on 32-bit WindowsServer 2003: tabadmin restore\Program Files\Tableau\Tableau Server\uninstall-8.1.tsbak
Remove Unneeded FilesAs a best practice, you shouldmonitor space usage on your server. If you need tomakemorespace available, you can remove log files, termporary files, and unneeded entries in thePostgreSQL database entries. If youmight need the older logs for troubleshooting an issue,you should create a log file archive before doing the cleanup. For more information, seeArchive Logs on Command Line (tabadmin) on page 378.To perform a cleanup, use this command:
tabadmin cleanup
You can add the restart option, which is the equivalent of running tabadmin stop,tabadmin cleanup, and then tabadmin start:
tabadmin cleanup --restart
- 369 -
The files and database entries that are removed by the tabadmin cleanup commanddepend on whether Tableau Server is running or stopped. Therefore, to clean up all possiblefiles and database entries, you should run tabadmin cleanup twice: once when TableauServer is running, and once when it is stopped. Here's a summary of what's removed whenyou run tabadmin cleanup with the server running and stopped.When you run tabadmin cleanup with Tableau Server stopped:
l All log files are removed from ProgramData\Tableau\TableauServer\data\tabsvc\logs
(log files from ProgramData\Tableau\Tableau Server\logs are notremoved).
l Temporary files are removed from ProgramData\Tableau\TableauServer\temp and ProgramData\Tableau\TableauServer\data\tabsvc\temp.
l No rows for HTTP requests are removed from the http_requests table of theTableau Server PostgreSQL database, because the database is not accessible whenthe server is stopped.
When you run tabadmin cleanup with Tableau Server running:
l Log files older than the log file rotation interval are removed fromProgramData\Tableau\Tableau Server\data\tabsvc\logs. (By default,the rotation interval is one day.) Active logs and log files fromProgramData\Tableau\Tableau Server\logs are not removed.
l Temporary files are not removed.
l Files that are in use (that is, locked by the operating system) are not removed.
l Rows for HTTP requests that are older than seven days are removed from the http_requests table of the Tableau Server PostgreSQL database.
Note: Rows for HTTP requests older than seven days are also removed whenyou back up Tableau data. For more information, seeBack Up the TableauData on page 366
More InformationFor more information about the http_requests table, seeCreate CustomAdministrative Views on page 163.For tips on how to automate running the cleanup and backup commands, refer to the followingKnowledge Base article: Server Backup andMaintenance Automation
If you have created a log file archive and no longer need it, you can remove it from your serverby using theDelete Snapshot option on theMaintenance page. For more information, seeArchive Logs on Maintenance Page (Snapshot) on page 375.
- 370 -
- 371 -
TroubleshootingUse the following topics to troubleshoot issues youmay be having with Tableau Server. Fortips on troubleshooting trusted authentication, see Troubleshoot Trusted Authenticationon page 277:
Work with Log FilesTableau Server creates log files as a normal part of its activities. Youmay need to use theserver log files when you are troubleshooting issueswith Tableau Sever or if Tableau Supportrequests logs to help you resolve an issue.
You can create a zipped log file archive (snapshot) from the command line on the server, orusing theGenerate Snapshot option on theMaintenance page. The zipped archive containscopies of the logs you can copy or download using a web browser, and send to TableauSupport. Once you have a copy of the archive, you can delete the archive from your server. Formore information on creating, downloading and deleting log file archives, seeArchive Logson Maintenance Page (Snapshot) on page 375.This collection of topics provides information about how to create log file archives, the contentsof specific log files, and details about when and how youmight want to look at a log.
Investigating Tableau Server IssuesThe range and complexity of possible issueswith Tableau Server means that there is no simpleprocess you can use to investigate all problems, but a general approach would include thesesteps:
1. Clean up existing log files to reduce their size. For more information, seeRemoveUnneeded Files on page 368.
2. Set the appropriate logging level. This is something that Tableau Support willinstruct you on. For more information, seeChange Logging Levels on page 385.
3. Reproduce the issue you are troubleshooting so the logs capture the events related tothe problem.
4. Create an archive of the logs. For more information seeArchive Log Files on page375.
Important:Use this archive when looking at the log files. You should not edit,move or delete any files directly on the server.
5. Review the server configuration file ( \config\tabsvc.yml) to get a basicunderstanding of the server environment.
6. Review the admin log (\logs\tabadmin.log) to understand anymaintenancethat has been done on the server.
Search for run as: <script> to find entries specific to tabadmin activity.
7. Review the Apache logs (\httpd\access.####_##_##_##_##_##.log and
- 372 -
\httpd\error.log) for requests that may be related to the issue you areinvestigating.
The Apache logswill contain a fair amount of "noise" that does not apply to issues youare experiencing.
l If you find a request that seems to be related to your issue, search \wgserverand \vizqlserver for entries that include the unique request ID from theApache logs.
l Look for the response code andmessage associated with the request ID.l Search for the name of the workbook, view, dashboard, or data source that isrelated to your issue. Make sure to look for a relevant timestamp.
l If you find a request that seems to be related to your issue, look at the responsecode associated with the request. (200s are good, 500s indicate problems.)
l Locate the unique request ID associated with the request you've identified (theunique request ID is a 24 character alphanumeric string at the very end of therequest).
8. Review the log archive further to search for other messages and possible errors.l Use the request ID from the Apache logs to search the \wgserver and\vizqlserver folders of the log archive for files containing related log entries.Look for indications of a problem (for example, error messages or long-runningqueries).
9. Contact supportIf you are not able to solve the issue yourself, or if requested by Tableau Support, sendthe zipped archive to Tableau.
See the following topics for more information:
Tableau Server ProcessesThere are six Tableau Server processeswhose default configuration you can change toachieve different results. The topics Improve Server Performance on page 228 andHighAvailability on page 45 describe some of the approaches you can take. High-level status foreach process is displayed on the server’sMaintenance page andmore detailed informationrelated to some of the processes—such as the background process—is in theAdministrativeViews on page 155 topic.Architecturally, the 64-bit version of Tableau Server uses native, 64-bit processes; the 32-bitversion of Tableau Server uses 32-bit processes. The exception is the data engine. If the 32-bitversion of Tableau Server is installed on a 64-bit operating system, the 64-bit version of thedata engine process is used.
For information on log files generated by these processes, seeServer Log File Locations onpage 379.
Process File Name Purpose Multi-Threaded?
PerformanceCharacteristics
application wgserver.exe Handles the web Yes Only consumes
- 373 -
Process File Name Purpose Multi-Threaded?
PerformanceCharacteristics
server application,supports browsingand searching
noticeable resourcesduring infrequentoperations, likepublishing a workbookwith an extract, orgenerating a static imagefor a view. Its load can becreated by browser-based interaction and bytabcmd.
background backgrounder.exeExecutes servertasks, includingextract refreshes,‘Run Now’ tasks,and tasks initiatedfrom tabcmd
No A single-threadedprocesswheremultipleprocesses can be run onany or all machines in thecluster to expandcapacity. Thebackgrounder normallydoesn’t consumemuchprocessmemory, but itcan consumeCPU, I/O,or network resourcesbased on the nature ofthe workload presentedto it. For example,performing large extractrefreshes can usenetwork bandwidth toretrieve data. CPUresources can beconsumed by dataretrieval or complextabcmd tasks.
data engine tdeserver64.exe
tdeserver.exe
Stores dataextracts andanswers queries
Yes The data engine'sworkload is generated byrequests from the VizQLServer process. It is thecomponent that loadsextracts intomemoryand performs queriesagainst them. Memoryconsumption is primarily
- 374 -
Process File Name Purpose Multi-Threaded?
PerformanceCharacteristicsbased on the size of thedata extracts beingloaded. The 64-bit binaryis used as the default on64-bit operatingsystems, even if 32-bitTableau Server isinstalled. The dataengine ismulti-threadedto handlemultiplerequests at a time.Under high load it canconsumeCPU, I/O, andnetwork resources, all ofwhich can be aperformance bottleneckunder load. At high load,a single instance of thedata engine canconsume all CPUresources to processrequests.
data server dataserver.exe Handlesconnections toTableau Serverdata sources
Yes Because it’s a proxy, it’snormally only bound bynetwork, but it can bebound byCPU withenough simultaneoususer sessions. Its load isgenerated by browser-and Tableau Desktop-based interaction andextract refresh jobs forTableau Server datasources.
repository postgres.exe Tableau Serverdatabase, storesworkbook anduser metadata
n/a Normally consumes fewresources. It canbecome a bottleneck inrare cases for very largedeployments (thousandsof users) whileperforming operationssuch as viewing all
- 375 -
Process File Name Purpose Multi-Threaded?
PerformanceCharacteristicsworkbooks by user orchanging permissions.
VizQLServer
vizqlserver.exe Loads andrenders views,computes andexecutes queries
Yes Consumes noticeableresources during viewloading and interactiveuse from aweb browser.Can be CPU bound, I/Obound, or networkbound. Process load canonly be created bybrowser-basedinteraction. Can run outof processmemory.
Archive Log FilesYou can create archives (snapshots) of log files in two different ways: from theMaintenancepage using a browser, or from a command prompt using tabadmin on Tableau Server.Creating a log file archive gives you a zipped snapshot of logs that you can use fortroubleshooting or to send to Tableau Support for help with an issue.
Archive Logs on Maintenance Page (Snapshot)
You can generate and download a snapshot (archive) of the Tableau Server log files from aweb browser, without opening a command prompt. This zipped snapshot contains a copy of upto seven days of log file data from Tableau Server and anyworker servers (if you have adistributed environment). The snapshot process does not change or remove either the TableauServer log files or the log archives created with tabadmin.
Note To specify the amount of data you want to collect or the name of the zip file you arecreating, use tabadmin to create an archive of server logs. For more information, seeArchive Logs on Command Line (tabadmin) on page 378.
To generate a snapshot of server log files:
- 376 -
1. On the Admin tab, clickMaintenance:
2. Under Activities, clickGenerate and download a snapshot of log files to open thesnapshot options:
3. ClickGenerate Snapshot to create a snapshot of the Tableau Server logs. TheGenerate Snapshot button is available only if there is no existing snapshot.
Log archives created with tabadmin do not affect the availability of this option.
4. ClickDownload Snapshot to download the log snapshot to your web browser's defaultdownload location. This option is available after you create a snapshot.
- 377 -
Google Chrome shows you the download in the bottom of the window:
5. Click the arrow and then clickOpen to unzip the snapshot or Show in folder to seewhere it was downloaded:
6. (Optional) ClickDelete Snapshot to delete a log snapshot. This option is available afteryou create a snapshot. You need to delete the existing snapshot before you can create anew one.
- 378 -
For example, youmight want to delete the snapshot that you created before an eventthat you want to investigate.
Archive Logs on Command Line (tabadmin)
You can archive Tableau Server log files using the tabadmin ziplogs command. Thiscommand creates a zip file containing all of the log files and is useful when you're working withTableau Support. The ziplogs command does not remove the log files, rather it copies theminto a zip file. If you are running a distributed installation of Tableau Server, perform this stepfrom the primary server. Anyworker logswill be included in the zip file.
Note: The tabadmin ziplogs commandmay generatemessages like "ziperror: Nothing to do!" These are generally related to specific steps in the zip process anddo not mean the log file archive is empty or the entire archive process failed.
To create log file archives:
1. Open a command prompt as administrator and navigate to the Tableau Server bin dir-ectory. For example:
cd "C:\Program Files\Tableau\Tableau Server\8.2\bin"
2. Stop Tableau Server by typing:
tabadmin stop
3. Create the zip file by typing tabadmin ziplogs -l -n <filename> where<filename> is the name of the zipped file you want to create. Choose a unique namewith no spaces. Tableau will not overwrite an existing file. For example:
tabadmin ziplogs -l -n my_logs
If you don't specify a file name, the file is named logs.zip. You can also use -dmm/dd/yyyy to only include logs generated since a certain date. For example:
tabadmin ziplogs -l -n -d 02/14/2014
The above command creates a zipped file named logs.zip that includes logs datedFebruary 14, 2014 up to the present; earlier logs are excluded. The -n option captures
- 379 -
information about the server environment, including which ports are in use. To see a listof all the ziplogs options, type tabadmin ziplogs -h.
4. Restart Tableau Server by typing:
tabadmin restart
You can find the zipped log file in the Tableau Server bin directory.
Server Log File Locations
By default, Tableau Server log file archives are gathered in a zip file called logs.zip (youcan specify a different name if you create the archive using tabadmin). You can copy thearchive from the server to a local computer and open it there, or send it to Tableau Support.When you unzip the archive, a series of folders are created with related log files. This tableexplains the possible contents of each folder, along with the original location the files camefrom on the Tableau Server, the process that created the log files, and details about the files.
The Tableau Server log directory is C:\ProgramData\Tableau\TableauServer\data\tabsvc\logs if you installed Tableau Server on drive C, unless otherwise noted inthe table below.Log Archive File Locations
Files/foldersin logs.zip
Details Files Generatedby
Location onTableau Server
build-
version.txt
The build ver-sion of TableauServer.
tabsvc.yml \config
wgserv-
er.checksumassetkey-
encryption
Logs related torepositoryencryption.
assetkeyencryption.log
tabadminassetkeys
\log-s\as-setkeyencryption
back-
grounder
Logs related tosubscriptionsand scheduledactivities likeextractrefreshes,"Run Now"tasks, and tab-cmd tasks.
backgrounder-#.log
spawn.####.log
tomcat-#.####-##-##.log
back-grounder.exe
\logs\backgrounder
config Configurationfiles.
connections.yml
workgroup.yml
TableauServer Con-figuration
\config
- 380 -
This is a goodplace to startgatheringinformationwhentroubleshooting. Confirm thattheconfigurationsettings arewhat youexpect.
data-
collector
\logs\datacollector
dataengine There will be atdeserver logfile for eachdaywith inform-ation aboutdata extractsand queries,and responsesto VizQL serverrequests.
tdeserver_####_##_##_##_##_##.log
tdeserver.exe
tdeserver64.exe
\logs\dataengine
dataserver Informationabout con-nections toTableauServer datasources.
dataserver-#.log data-server.exe
\logs\dataserver
httpd Apache logs.Look here forauthenticationentries. Eachrequest in theApache log willhave a requestID associatedwith it. Thisrequest ID isusedthroughout theserver logs and
access.####-##-##.##-##-##log
error.log
startup.log
Apache dae-mon
\logs\httpd
- 381 -
you can use itto associate logentries with arequest.
licensing \logs\licensing
logs This is thelocation of thelogs of mostinterest andusefulness.Look here afterreviewing theconfigurationfiles.
tabadmin.log isneveroverwritten ortruncated so itcontains all thedetails.
notify-tabadmin.logcontains errorsfromtabadmin.log(the errors arealso included intabadmin.log).
tablicsrv.logandtabsrvlic.logare related tolicensing.
tabadmin.log
tabconfig.log
tablicsrv.log
tabsrvlic.log
wgserver.war.deploy.log
\logs
pgsql PostgreSQLdatabase logs,including filesrelated tolaunchingserver pro-cesses.T-ableau dataextracts are
tabspawn \logs\pgsql
- 382 -
stored in thePostgreSQLdatabase.
repository postgres.exe \logs\repository
rsync Related to syn-chronization ofmain repositoryand standby inhigh-availabilityenvironments.Only applies tohigh-availability(HA) install-ations.
\logs\rsync
service notify-tabsvc.log
tabsvc.log
\logs\service
solr Related tosearch index-ing.
\logs\solr
svcmonitor \logs\svcmonitor
tabad-
minservice
Related to logarchives cre-ated using theGenerate aSnapshot ofServer LogFiles option.
\log-s\tabadminservice
tabadmwrk \logs\tabadmwrk
vizportal \logs\vizportal
vizqlserver Related toshowing andinteracting withviews.
When runningmultipleinstances ofVizQL Server,the instancesaredistinguished
vizql-0.log.####-##-##
spawn.####.log
vizqlserv-er.exe
\logs\vizqlserver
- 383 -
by portnumber.notify-productionlogs containexceptionalevents.
vizqlserver-
\logs
Most files are inJSON format.
tabprotosrv.txtis createdwhen you opendata or connectto data.
backgrounder_####_####_##_##_##_##_##.txt
dataserver_####_####_##_##_##_##_##.txt
tabadmin_####_##_##_##_##_##.txt
tabprotosrv.txt
vizqlserver_####_####_##_##_##_##_##.txt
wgserver_####_####_##_##_##_##_##.txt
tdserver_vizqlserver_####_####_##_##_##_##_##.txt
\vizqlserver\logs
wgserver Informationrelated toadministrativetasks,workbook andpermissionsmanagement,authentication,sign-ins, initialview requests,and publishingrequests.
Browsing,searching.
db-migrate_####_##_##_##_##_##.log
migrate.log
notify-production.####_####_##_##_##_##_##.log
production.####.log
production.####_####_##_##_##_##_##.log
wgserver.exe \logs\wgserver
- 384 -
Instances ofwgserver aredistinguishedby portnumber,immediatelyfollowing"production" or"notify-production".
notify-production logscontainexceptionalevents.
There will be aseparateproduction.n_### file foreachbackgrounderprocess foreach day.
notify-production.n_### correlatestoproduction.n_### butcontains onlyerrors.
spawn.####.log
tomcat-#.####_##_##.log
wgserver-#.log
Tableau Server log files can be found in the following folders on the server:Tableau Service Logs
The following log files track activities related to the web application, database, and index:
C:\ProgramData\Tableau\Tableau Server\data\tabsvcVizQL Logs
These log files track activities related to displaying views, such as querying the database andgenerating images:
C:\ProgramData\Tableau\Tableau Server\data\tabsvc\vizqlserver\Logs
- 385 -
Temporary Files
Any file that starts with exe_ in the folder below is a Tableau Server file and can be deleted.
C:\ProgramData\Tableau\Tableau Server\temp
Change Logging LevelsBy default, Tableau Server logs events at the Info level. You can change this if you need togather more information (if you are working with Tableau Support, for example). As a bestpractice you should not increase logging levels except when troubleshooting an issue.
Logging Levels
The following logging levels are listed in order of increasing amount of information logged:
l offl fatall errorl warnl info (the default)l debugl trace
Note: Increasing the log level to debug or trace increases the amount of informationbeing logged and can have a significant impact to performance. You should only set alogging level to debug when investigating a specific issue. Reproduce the issue and thenreset the logging level back to info.
Change Logging Levels
Set logging levels for Tableau Server using one of several tabadmin set commands. Thecommand you use depends on which component of Tableau Server you want to change thelogging level for.
Command Location of affected logs(path begins with \ProgramData\Tableau\TableauServer\data\tabsvc)
server.log.level \vizqlserver\Logs\*.txtvizqlserver.log.level \vizqlserver\*.logwgserver.log.level \wgserver\*.log
For more information, see tabadmin set options on page 358.You need to stop Tableau Server before changing the logging levels, and restart it afterward. Ifyou are running a distributed installation of Tableau Server, set logging levels from the primaryserver.
To change the logging level:
- 386 -
1. Open a command prompt as administrator and navigate to the Tableau Server bindirectory.
If Tableau Server is installed on the C drive:
C:\Program Files\Tableau\Tableau Server\8.2\bin
or
C:\Program Files (x86)\Tableau\Tableau Server\8.2\bin
2. Stop Tableau Server by typing:tabadmin stop
3. Set the logging level to by typing tabadmin set [command][option]
where [command] is server.log.level, vizqlserver.log.level orwgserver.log.level
and [option] is a valid logging level.
Examples:
l tabadmin set server.log.level debug
l tabadmin set vizqlserver.log.level warn
l tabadmin set wgserver.log.level off
4. Restart Tableau Server by typing:tabadmin restart
Reset Logging Levels
After you gather the information related to the issue you are investigating, reset the logginglevels so there is no lingering performance impact.
Reset the logging level back to its default (info) using the appropriate commandwith a -doption.
Examples:
l tabadmin set server.log.level -d
l tabadmin set vizqlserver.log.level -d
l tabadmin set wgserver.log.level -d
Handle an Unlicensed ServerTableau offers two licensingmodels: user-based and core-based. User-based licensingrequires each active user account to be covered by a license. User-based licenses have a
- 387 -
defined capacity, or number of users that it allows. Each user has a unique username assignedto him on the server and is required to identify himself when connecting to the server. Thesoftwaremay be installed on a singlemachine or distributed across any number of machines ina distributed server environment.
Core-based licensing has no constraints on the number of user accounts in the system, but itdoes restrict themaximumnumber of processor cores that Tableau Server can use. Youmayinstall the server on one or moremachines to create a cluster, with the restrictions that the totalnumber of cores in all themachines do not exceed the number of cores you have licensed andthat all of the cores on a particular machine are covered by the license.
Unlicensed User-Based ServerThemost common reason for a server that has user-based licensing to be unlicensed is anexpired product key or an expiredmaintenance contract. You can see your products keys andadd new ones by selectingStart > All Programs > Tableau Server > Manage ProductKeys.
Unlicensed Core-Based ServerA core-based server can become unlicensed for a variety of reasons. A common problem isthat the primary or a worker machine hasmore cores than the license allows.When the serveris unlicensed youmay not be able to start or administer the server. You can, however, manageyour licenses using the tabadmin command line tool. Follow the steps below to see a list of yourlicenses and number of cores bymachine.
1. Open a command prompt and type the following: cd C:\ProgramFiles\Tableau\Tableau Server\8.2\bin
2. Type the following: tabadmin licenses.
Handle an Unlicensed VizQL Server ProcessThere are several status indicators on the Tableau Server Maintenance page that help youunderstand the state of Tableau Server processes. An orange-color status box, "Unlicensed",indicates that one of the VizQL server processes is unable to retrieve the Tableau Serverlicense information.
Theremay be several reasonswhy the process is unable to access this information. Forexample, theremay be network issues preventing a VizQL process, which is running on aworker machine, from communicating with the primarymachine. Or, the processmay be
- 388 -
getting sent more requests than it can accept at that time and can’t handle the licensingrequest. As a result, some of your usersmay be able to access viewswhile others cannot.
To resolve the problem, stop, then start Tableau Server.
VizQL ‘Out of Memory’ ErrorIn 32-bit versions of Tableau Server, if a VizQL process reaches its limit of concurrent viewingsessions youmay see an ‘Out of Memory’ error, which will also be written to the vizqlserver*.txtlogs located here:C:\ProgramData\Tableau\TableauServer\data\tabsvc\vizqlserver\Logs
The VizQL process doesn’t terminate when this error occurs, but it will not accept additionalconnections. You can handle this problem by doing the following:
l Upgrading to the 64-bit version of Tableau Server: SeeUpgrade to 8.2 on page29 for details.
l Increasing the number of VizQL processes: Thismaymean that you need to addone or more workers. See Install and Configure Worker Servers on page 40 for howto do this.
l Edit vizqlserver.session.expiry.timeout: Use tabadmin to change thevizqlserver.session.expiry.timeout setting from its default (30minutes) to a shorter timeperiod such as 10 or 5minutes. This will allow idle sessions to expire sooner, thusfreeingmemory for new sessions.
Cookie Restriction ErrorWhen a user signs in to Tableau Server, a session cookie is stored in their local browser. Thestored cookie is how Tableau Server maintains that the signed in user has been authenticatedand can access the server. Because the cookie is set with the same domain or sub-domain asthe browser's address bar, it is considered a first-party cookie. If a user's browser is configuredto block first-party cookies, theywill be unable to sign in to Tableau Server.
When a user signs in to Tableau Server via an embedded view, or in an environment wheretrusted authentication has been configured, the same thing happens: a cookie is stored. In thiscase, however, the browser treats the cookie as a third-party cookie. This is because thecookie is set with a domain that's different from the one shown in the browser's address bar. Ifa user's web browser is set to block third-party cookies, authentication to Tableau Server willfail. To prevent this from occurring, web browsersmust be configured to allow third-partycookies.
Troubleshoot Data SourcesFor users to work with Tableau Server data sources, up to three things need to be in place:
- 389 -
l Permissions for the data source: Anyone connecting to a data sourcemust have theConnect andView permissions for it. This also applies to users accessing views thatconnect to data sources. Anyone publishing andmodifying data sourcesmust belicensed to Publish and also have theWrite/Save As andDownload/Web Save Aspermissions. SeeWork with Permissions on page 188 andSet Permissions for aData Source on page 192 for more information.Multidimensional (cube) data sources have to be downloaded and used in TableauDesktop, so they requireDownload/Web Save As permission. For more informationabout cubes in Tableau, seeMultidimensional (Cube) Data Sources on page 144.
l Ability to authenticate to the database: There are several ways you can connect todata in Tableau and control who has access to what. Basically, whichever entity isconnecting to the databasemust be able to authenticate. The entity could be TableauServer performing an extract refresh. It could be a Tableau Desktop user connecting to adata source that then connects to a live database. It could also be a Tableau Server userwho’s accessing a view that connects to a live database. Refer toData Security onpage 220 to learnmore about your options.
l Database drivers: If the person who created and published the data source in TableauDesktop needed to install additional database drivers, youmay need to install them onTableau Server aswell. If you are running a distributed installation of Tableau Serverwhere, for example, the data server process is running on a worker server, any requireddatabase driversmust be installed there aswell as on the primary server. Otherprocesses require drivers aswell. SeeDatabase Drivers on page 42 for moreinformation.
Data Source Error MessagesHere are some errors that workbook authors and other usersmay encounter as theywork withdata sources and views:
Permission to access this Tableau Server data source denied:Connecting to a datasource requires the Connect permission. SeeWork with Permissions on page 188 andSetPermissions for a Data Source on page 192 for more information.Data source not found: Someoneworking with a view may see this error if a data source isremoved from Tableau Server or if their Connect to Data page needs to be updated. To updatethe Connect to Data page in Tableau Desktop, click the Refresh icon:
- 390 -
Unable to connect to this Tableau Server data source: This error may appear if theconnection information for the data source has changed—for example, as a result of thedatabase server name changing. Look at the Data Connection information for the data sourceand confirm that it has the correct settings.
Unable to list Tableau Server data sources: This error may occur if a user is trying toaccess Tableau Server data sources and there are connectivity issues between TableauServer and Tableau Desktop.
Can’t connect with a cube data source: To use a publishedmultidimensional (cube) datasource, youmust download the data source and use it in Tableau Desktop. Verify that youhave the Download/Web Save As permission for the data source. For more informationabout cubes in Tableau, seeMultidimensional (Cube) Data Sources on page 144.
Troubleshoot Subscriptions
"The view snapshot in this email could not be properly rendered."If you receive a subscription with this error message, there could be several reasons:
l Missing credentials: Some views are published with embedded credentials.Youmayreceive the above error if the embedded credentials are now out-of-date, or if the viewwas republished without the embedded credentials.
l Database temporarily down: If the view has a live database connection and thedatabase was temporarily downwhen the subscription was being generated, youmightreceive the above error.
l Background process timeout: By default, the background process that handlessubscriptions times out after 30minutes. In themajority of cases, this is plenty of time.However, if the background process is handling an extraordinarily large and complexdashboard, that may not be enough time. You can check theBackground Tasks onpage 159 admin view to see if that's the case. To increase the timeout threshold, use thetabadmin option subscriptions.timeout.
Can't SubscribeIf you can see a view on Tableau Server and it has a subscription icon ( ) in the upper rightcorner, you can subscribe to it.
Two things need to be in place for you to subscribe to a view: Tableau Server needs to becorrectly configured (described inManage Subscriptions on page 104) and the view you'resubscribing tomust either have embedded credentials for its data source or not rely oncredentials at all. Examples of the latter include a workbook that connects to an extract that isn'tbeing refreshed, or a workbookwhose data is in a file that was included with the workbook atpublish time. Embedding credentials is a step that happens in Tableau Desktop (see theTableau Desktop help for details).
- 391 -
No Subscription IconIt's possible to see a view on Tableau Server but be unable to subscribe to it. This happens forviewswith live database connections, where you’re prompted for your database credentialswhen you first click the view. A subscription includes a view (or workbook), data, and aschedule. To deliver the data piece, Tableau Server either needs embedded databasecredentials or data that doesn't require credentials. Where live database connections areconcerned, Tableau Server doesn't have the credentials, only the individual users do. This iswhy you can only subscribe to views that either don’t require credentials or have themembedded.
Youmay also be able to see a view but be unable to subscribe to it (no subscription icon) ifTableau Server is configured for trusted authentication. See Subscription Requirements formore information.
Receiving Invalid or "Broken" SubscriptionsIf you configured subscriptions on test or development instances of Tableau Server in additionto your in-production instance, disable subscriptions on your non-production instances.Keeping subscriptions enabled on all instances can result in your users receiving subscriptionsthat appear to be valid, but which don't work, or receiving subscriptions even though they'veunsubscribed from the view or workbook.
Subscriptions not Arriving ("Error sending email. Can't send command toSMTP host.")Youmay see the above error inWindowsEvent Viewer if subscriptions appear to be sent(according to theBackground Tasks on page 159 admin view), yet subscriptions aren'tarriving, and your SMTP server is using encrypted (SSL) sessions. Subscriptions are onlysupported for unencrypted SMTP connections. The solution is to use an unencrypted SMTPserver.
Custom Scripts not Working after Upgrade to 8.1To support better sessionmanagement, starting with version 8.1, a hash tag (#) was added tothe end of view URLs. If you had custom subscriptions scripting that generated views as PDFsor PNGs youmay need to update your scripts to allow for the hash tag.
For example, prior to version 8.1, view URLswere like this:http://tableauserver/views/SuperStore/sheet1 and you could generate a viewas a PNGby adding .png to the end of the URL, such as:http://tableauserver/views/SuperStore/sheet1.png. Starting with version8.1, view URLs are like this:http://tableauserver/views/SuperStore/sheet1#1. To generate a PNG, add.png before the hash tag. For example:http://tableauserver/views/SuperStore/sheet1.png#1
- 392 -
Troubleshoot SAMLUse the following topics to troubleshoot SAML issues.
SAML and Enable Automatic LogonIf you are using SAML and Tableau Server is also configured to use Active Directory, do notalso selectEnable automatic logon. Enable automatic logon and SAML cannot both beused.
Signing In from the Command LineEven if Tableau Server is configured to use SAML, it is not used if you sign in to Tableau Serverusing the command line tools tabcmd on page 319 or the Tableau Data Extract command lineutility (provided with Tableau Desktop).
Login FailedIf you receive themessage "Login failure: Identity Provider authentication successful for user<username from IdP>. Failed to find the user in Tableau Server." the usernames as stored inTableau Server and as stored in your IdP are not identical. To fix this, make sure that theymatch. For example, if Jane Smith's username is stored in the IdP as jsmith it must be storedin Tableau Server as jsmith.
SAML Error LogSAML authentication takes place outside Tableau Server, so troubleshooting authenticationissues can be difficult, but any login attempts are logged by Tableau Server. You can create asnapshot of log files and use them to troubleshoot problems. For more information, seeArchive Log Files on page 375.
Note: Normal SAML events are only logged if wgserver.log.level is set to debug.For more information, seeChange Logging Levels on page 385.
Check for SAML errors in the following files in the unzipped log file snapshot:
\wgserver\wgserver-<n>.log
\wgserver\production.<nnnn>_<yyyy_mm_dd_hh_mm_ss>.log
Trailing SlashOn the SAML tab, confirm that the Tableau Server return URL does not end with a trailingslash (correct: http://tableau_server; incorrect: http://tableau_server/):
- 393 -
Confirm ConnectivityConfirm that the Tableau Server you are configuring has either a routeable IP address or aNAT at the firewall that allows two-way traffic directly to the server.
You can test your connectivity by running telnet on Tableau Server and attempting to connectwith the SAML IdP. For example: C:\telnet 12.360.325.10 80
The above test should connect you to the HTTP port (80) on the IdP and you should receive anHTTP header.
Handle Extract Refresh AlertsIf scheduled extract refreshes did not succeed, Tableau displays an Alertsmenu in the upperright corner:
You will see the Alertsmenu only if an extract refresh failed and you are:
l A system or site administrator.
l The author of the workbook or data source that couldn’t be refreshed.
l The author of a workbook that connects to a data source that couldn’t be refreshed.
When you open the Alertsmenu you can seemore information about the refresh failure(s):
- 394 -
When aData source is listed as Embedded it means that the data source definition (whichincludes things like the data source credentials or the database name) is embedded, orresides, within the workbook itself, originally created in Tableau Desktop.
When a data source name or workbook name is listed as theData source (for example,Datasource: sales_data), it means that the data source is a Tableau Server data source. The datasource definition resides on Tableau Server.
In the Data window, you can identify workbooks or data sources that were originally created inTableau Desktop. A Tableau icon instead of a database icon is displayed next to the datasource name:
- 395 -
Resolving Extract Refresh ProblemsYou can resolve some extract refresh problems by clicking theEdit connection info link in thealert, and then entering themissing information, and clickingSave:
If the problem cannot be corrected by editing the data connection, you will need to resolve it inTableau Desktop and republish the workbook.
Tip: Administrators can edit data connections at any time on theData Connections page,accessible from theAdmin tab.
- 396 -
JavaScript APIWith Tableau's JavaScript API you can integrate Tableau visualizations into your ownwebapplications. The API lets you tightly control your users' interactions and combine functionalitythat otherwise couldn't be combined. For example, you can code a single control that filters agroup of marks, selects some of thosemarks, and presents their data for download. See thetopics below for details:
l Requirementsl Conceptsl Tutoriall API Reference
RequirementsThe requirements for the Tableau JavaScript API are as follows:
Access to a Tableau server: To programwith the Tableau JavaScript API you need to haveaccess to Tableau Server, TableauOnline, or Tableau Public, and a published workbook onthat server. Your web application shouldn’t be on the same computer as the server, but itneeds to be able to access the server. For information about the API and accessing it, seeConcepts below.A supported browser: Your end-users can experience the web application you create inmost supported web browsers; specifically, Chrome, Firefox, Safari 3.2.1 and later, andInternet Explorer 8.0 and later. If you are using Internet Explorer 8.0, it must have compatibilitymode disabled. Additionally, your browser must be configured to allow the use of thewindow.postMessagemethod in the JavaScript code. This feature is disabled by some securitypackages.
ConceptsThis topic is designed for people familiar with JavaScript and object-oriented programmingconcepts. You should also be familiar with Tableau visualizations from a user's point of view. Ifyou are just getting started, a good place to begin is the Tutorial.
Programming ApproachThe Tableau JavaScript API uses an object model. The entry point into the object model is toinstantiate a new Viz object as follows:
var viz = new tableauSoftware.Viz(/* params omitted */);
Nearly every Tableau object allows you to navigate back to its parent Viz object by way of"parent" properties on the object.
- 397 -
Accessing the APIThe API is about programmatically controlling embedded views published to Tableau Serveron premise or a Tableau hosted server. To use it, you need access to a server running version8.0 or later, and a published workbook on that server.
The API is provided through the file tableau_v8.js (minified) or tableau_v8.debug.js. In webpages that contain your JavaScript code for rendering Tableau views, you can reference theAPI files using the following address:http://<your_server_name>/javascripts/api/
For example, using the server name localhost, you would add the following code in the pageheader:
<script type="text/javascript"src="http://localhost/javascripts/api/tableau_v8.js"></script>
The file system location of these files is ProgramFiles\Tableau\Tableau Server\8.2\wgserver\public\javascripts\api.
Working With Tableau Hosted Servers
If you publish workbooks to TableauOnline or Tableau Public, you can access the API thatmatches the server product you use.
l For TableauOnline, use the following location:https://online.tableausoftware.com/javascripts/api/
l For Tableau Public, use the following location:https://public.tableausoftware.com/javascripts/api/
To the URL, add the file name for the API you want to use (tableau_v8.js or tableau_v8.debug.js), as shown in the example code earlier in theAccessing the API above section.
Important: For best code stability, use the API location for the server product you workwith. For example, if you publish workbooks to an on-premise Tableau Server, use theJavaScript API local to your server.
BootstrappingThere is only one entry point into the API: instantiating a new Viz object, which creates theHTML necessary to embed a Tableau visualization. To instantiate a new Viz object, simplycall the Viz constructor via new, passing the required parentElement and URL parametersand an optional set of options. The URL parameter is where you specify the name of theTableau server:
- 398 -
var placeholderDiv = document.getElementById("tableauViz");var url = "http://tabserver/views/workbookname/viewname";var options = {
hideTabs: true,width: "800px",height: "700px"
};var viz = new tableauSoftware.Viz(placeholderDiv, url, options);
Trusted Authentication
If Tableau Server is using trusted authentication, specify the ticket in the URL by first addingtrusted after the server name, followed by the ticket. For example:
var placeholderDiv = document.getElementById("tableauViz");var url = "http://tabserver/trusted/Etdpsm_Ew6rJY-9kRrALjauU/views/workbookname/viewname";var options = {
hideTabs: true,width: "800px",height: "700px"
};var viz = new tableauSoftware.Viz(placeholderDiv, url, options);
Property Getters and SettersGetters and setters are always functions that start with get or set. They can be calledmultiple timeswith little performance impact (in other words, they should simply return cachedfields or do very simple calculations). Properties are always synchronous and returnimmediately with the value, rather than having a callback function.
Call Behavior - AsynchronousBy default, calls are asynchronous sincemany of themmay require a roundtrip to the server.Methods use the following naming convention:
l Asynchronous calls are indicated by an Async suffix on themethod name, for example,Worksheet.applyFilterAsync().
l Asynchronous calls return a Promise object, allowing chaining.
The Tableau JavaScript API uses the CommonJS Promises/A standard. The premise behindTableau's implementation is that asynchronousmethods return an object that has a thenmethod in the following form:
then(fulfilledHandler, errorHandler)
- 399 -
The fulfilledHandler is called when the promise is fulfilled (on success). TheerrorHandler is called when a promise fails. All arguments are optional and non-functionvalues are ignored.
Chaining Promises
The promised result of an asynchronousmethod is passed as the parameter to the next then()method. For example:
var activeSheet;viz.getWorkbook().activateSheetAsync("Sheet 1")
.then(selectLemon).then(filterToLemonAndMint);
function selectLemon(sheet) {activeSheet = sheet;return sheet.selectMarksAsync("Product", "Lemon", "replace");
}
function filterToLemonAndMint() {return activeSheet.applyFilterAsync("Product", ["Lemon",
"Mint"], "replace");}
The result of activateSheetAsync() is a promise to eventually return the Sheet objectthat was activated, which is passed as the first parameter to the selectLemon()method.Notice that the selectLemon() method returns a Promise object (the return value of theselectMarksAsync()method), not the result after themarks have been selected.However, since it’s a Promise object, the next then()method is not called until that promiseis fulfilled.
If a link in the chain is added after the promise has been fulfilled, the callbackwill beimmediately called with the value that was previously returned. As the programmer, thismeansyou don't need to determine if the response has already been received from the server. Theasynchronousmethodswill always be called, whether it's now or later.
var promise = viz.getWorkbook().activateSheetAsync("Sheet 1");
// Pretend that activatSheeteAsync() has already returned fromthe server.promise.then(callback);
// callback will be called immediately using the Sheet object// returned from activateSheetAsync()
- 400 -
Return Values of Then() Methods
Whatever is returned in a then()method will get passed as the first parameter to the nextthen()method. It can be a scalar value (Number, Boolean, String, etc.), an object, oranother Promise. The infrastructure will automatically wrap non-Promise values into aPromise value so that they can be chained.
viz.getWorkbook().activateSheetAsync("Sheet 1")
.then(function (sheet) {return "First link";
})
.then(function (message) {if (message === "First link") { alert("Expected"); }// no return value here means nothing is passed to the next
link})
.then(function () {});
Breaking Out of a Chain
Technically, there’s no way to break out of a chain since that would invalidate the guaranteethat subsequent links in the chain will be called. If there is an exception thrown in part of thechain, the rest of the chain is run but the errorHandler is called instead of thefulfilledHandler.
If a link in the chain depends on the results of earlier links, then you should write an ifstatement to check your condition. Here's an example:
viz.getWorkbook().activateSheetAsync("Sheet 1")
.then(function (sheet) {// I’m returning a Promisereturn sheet.selectMarksAsync("Product", "NoProduct",
"replace");})
.then(function () {return viz.getWorkbook().getActiveSheet().getSelectedMarksAsync
();})
.then(function (marks) {// The getSelectedMarksAsync call succeeded, but no marks were
- 401 -
selected// because there are not any marks corresponding to
"NoProduct".if (marks.length === 0) {
throw new Error("No marks selected");}
var firstMarkValue = marks[0].getPairs().get("Product").value;return sheet.applyFilterAsync("Product", firstMarkValue,
"replace");})
.then(function (filterName) {// applyFilterAsync succeeded
}, function(err) {if (err.message === "No marks selected") {
alert("This was caused by the first link above");}
})
.otherwise(function (err) {alert("We handled the error above, so it’s not propagated to
this handler.");});
If a callback is not provided (or is null or undefined), then the results are passed to the next linkin the chain:
viz.getWorkbook().activateSheetAsync("Sheet 1").then().then(function (sheet) {
// this is called});
In this way, you can specify a single otherwise function to handle all errors in the chain. Thealways function works the sameway, but it is called regardless of success or failure. Thethen/otherwise/always functionswork similarly to a try/catch/finally block.
viz.getWorkbook().activateSheetAsync("Sheet 1").then(function () {
return sheet.selectMarksAsync(...);}).then(function (marks) {
// Do something with the marks.
- 402 -
}).otherwise(function (err) {
// I’m handling all errors in one place.console.log(err.message);
}).always(function () {
// Do some cleanup or logging});
CollectionsMany classes have collections of items, where each item has a key (typically an ID or a name).Examples include a collection of sheets keyed by name or the list of parameters on a sheetkeyed by name. Collections are publicly immutable, exposing read-only functionality. EachCollection array is keyed with its elements’ identifiers. For example, the result ofWorkbook.getPublishedSheetsInfo() is an array with the index corresponding tothe position of the sheet in the workbook. It is also keyed by the sheet name so that you canaccess it like this:
var sheet = workbook.getPublishedSheetsInfo()[0];var sameSheet = workbook.getPublishedSheetsInfo().get("Sheet 1");
Collection Interface
Name ReturnType
Description
get(key :string)
Collectionitem type
Gets the element in the collection associated with the key, orundefined if there is nothing associated with it.
has(key: string)
bool Returns true if there is an element in the collection associatedwith the key; otherwise, false.
EventsThe Viz class acts as the central event hub. This way you only have to go to one place for allevents. It alsomeans that events can be raised on an object that may not have been createdyet. For example, the marksselection event can be raised for a particular sheet eventhough the Sheet object hasn't been created yet. Each event contains an anonymous objectwith information pertaining to that event, such as the sheet the event occurred on.
Listening to an event is done by calling Viz.addEventListener(type, callback)and passing in a function callback. Here's an example of listening to an event:
viz.addEventListener("marksSelection", function (marks) {changeMySelectionUI(marks);
});
- 403 -
Removing a listener is done by calling Viz.removeEventListener(type, listener)and passing in the same callback function that was passed into Viz.addEventListener(). For example:
function changeMySelectionUI(marks) {viz.removeEventListener("marksSelection", changeMySelec-
tionUI);}viz.addEventListener("marksSelection", changeMySelectionUI);
Events aremulticast delegates, meaning that multiple listeners are supported. The order inwhich notifications are called is not specified. Every event callback takes a single objectcontaining a pointer to the Viz that raised the event. Each event also adds additional fields tothe event, as specified in theAPI Reference on page 408.
FilteringWhen you program filtering you aremimicking the user behavior of clicking a filter in a view tonarrow down the data that is displayed. Here's an example of filtering on a single value:
worksheet.applyFilterAsync("Container", "Jumbo Box",tableauSoftware.FilterUpdateType.REPLACE);
There is a difference between querying existing filter state and setting new or existing filters.Querying filters is done via Worksheet.getFiltersAsync() which returns a collectionof Filter classes. Setting filters is done via Worksheet.applyFilterAsync (and itsvariants) and is a function call that doesn't require you to instantiate a Filter class.
When you specify fields in a filter, you should use the caption as shown in the user interface,not the database field name. For example, you should useContainer (the caption) instead ofProduct Container (the actual field name). In some cases, Tableau Desktop renames fieldsafter they've been dragged to a shelf. For example theDate field might be renamed toYEAR(Date) after being dragged to the rows shelf. In this case, you should useYEAR(Date) as theparameter. The exception is hierarchical filters, which use the full hierarchical name (forexample, [Product].[All Product].[Espresso]). Captions can use the optional []delimiters around names.
Here are samples for many types of filtering:
var worksheet;viz.getWorkbook().activateSheetAsync("Sheet 4").then(function(sheet) {
worksheet = sheet;})
// Single value.then(function () {
return worksheet.applyFilterAsync("Product Type", "Coffee",
- 404 -
tableauSoftware.FilterUpdateType.REPLACE);})
// Multiple values.then(function () {
return worksheet.applyFilterAsync("Product Type", ["Coffee", "Tea"],tableauSoftware.FilterUpdateType.REPLACE);
})
// Multiple Values - adding and removing.then(function () {
return worksheet.applyFilterAsync("Product", ["Lemon", "Mint"],tableauSoftware.FilterUpdateType.ADD);
})
.then(function () {return worksheet.applyFilterAsync("Product", ["Caffe Latte",
"Green Tea"],tableauSoftware.FilterUpdateType.REMOVE);
})
// All values.then(function () {
return worksheet.applyFilterAsync("Product Type", "",tableauSoftware.FilterUpdateType.ALL);
})
// Date Range.then(function () {
return; worksheet.applyRangeFilterAsync("Date", {min: new Date(Date.UTC(2010, 3, 1)),max: new Date(Date.UTC(2010, 12, 31))
});})
// Clearing a Filter.then(function () {
return worksheet.clearFilterAsync("Date");})
// Relative Date.then(function () {
- 405 -
return worksheet.applyRelativeDateFilterAsync("Date", {anchorDate: new Date(Date.UTC(2011, 5, 1)),periodType: tableauSoftware.PeriodType.YEAR,rangeType: tableauSoftware.DateRangeType.LASTN,rangeN: 1
});})
// Quantitative Filters// SUM(Sales) > 2000 and SUM(Sales) < 4000.then(function () {
return worksheet.applyRangeFilterAsync("SUM(Sales)", {min: 2000,max: 4000
});})
// SUM(Sales) > 1000.then(function () {
return worksheet.applyRangeFilterAsync("SUM(Sales)", {min: 1000
});})
// Hierarchical Filters - selecting all on a level.then(function () {
return worksheet.applyHierarchicalFilterAsync("[Product].[Product Categories]", {
levels: [0, 1]}, tableauSoftware.FilterUpdateType.ADD);
}, function (err) { /* ignore errors */ })
// Hierarchical Filters - adding one item.then(function () {
return worksheet.applyHierarchicalFilterAsync("[Product].[Product Categories].[Product Name]","Accessories.Bike Racks.Hitch Rack - 4-Bike",tableauSoftware.FilterUpdateType.REPLACE);
}, function (err) { /* ignore errors */ })
// Hierarchical Filters - adding multiple items.then(function () {
return worksheet.applyHierarchicalFilterAsync("[Product].[Product Categories].[Product Name]",
- 406 -
["Accessories.Bike Racks.Hitch Rack - 4-Bike","Accessories.Bike Stands.All-Purpose Bike Stand"
],tableauSoftware.FilterUpdateType.REPLACE);
}, function (err) { /* ignore errors */ })
.otherwise(function (err) {console.log(err);
});
Selecting MarksSelectingmarks is almost identical to filtering. For filtering,you use one of theWorksheet.applyFilterAsync()methods. For selectingmarks, you useWorksheet.selectMarksAsync(). The parameters for mark selection are almostidentical to those used for filtering.
worksheet.selectMarksAsync("Product", "Caffe Latte",tableauSoftware.SelectionUpdateType.REPLACE);
Here are samples of other types of selecting you can use:
var worksheet;viz.getWorkbook().activateSheetAsync("Sheet 4").then(function(sheet) {
worksheet = sheet;})
// Single dimensions work just like filtering
// Single dimension - single value.then(function () {
return worksheet.selectMarksAsync("Product", "Mint",tableauSoftware.SelectionUpdateType.REPLACE);
})
// Single dimension - Multiple values.then(function () {
return worksheet.selectMarksAsync("Product", ["Chamomile", "Mint"],tableauSoftware.SelectionUpdateType.REPLACE);
})
// Single dimension - Multiple values (delta).then(function () {
- 407 -
return worksheet.selectMarksAsync("Product", ["Lemon", "EarlGrey"],
tableauSoftware.SelectionUpdateType.ADD);}).then(function () {
return worksheet.selectMarksAsync("Product", ["Chamomile", "Earl Grey"],tableauSoftware.SelectionUpdateType.REMOVE);
})
// Quantitative selection.then(function () {
return worksheet.selectMarksAsync({"State": ["Florida", "Missouri"],"SUM(Sales)": { min: 3000, max: 4000 }
}, tableauSoftware.SelectionUpdateType.REPLACE);})
// Hierarchical dimensions.then(function () {
return worksheet.selectMarksAsync("[Product].[Product Categories].[Category]","Bikes",tableauSoftware.SelectionUpdateType.REPLACE);
}, function (err) { /* ignore errors */ })
// Multiple dimensions - multiple values// ((State = Washington OR Oregon) AND Product = Lemon)// OR// (State = Oregon AND Product = Chamomile).then(function () {
return worksheet.selectMarksAsync({"State": ["Washington", "Oregon"],"Product": "Lemon"
}, tableauSoftware.SelectionUpdateType.REPLACE);}).then(function () {
return worksheet.selectMarksAsync({"State": "Oregon","Product": "Chamomile"
}, tableauSoftware.SelectionUpdateType.ADD);})
// Round-tripping selection
- 408 -
.then(function () {return worksheet.selectMarksAsync(
"Product","Lemon",
tableauSoftware.SelectionUpdateType.REPLACE);}).then(function () {
return worksheet.getSelectedMarksAsync();}).then(function (marks) {
// filter out only the Washington and Oregon marksvar onlyWashingtonAndOregon = [];for (var i = 0, len = marks.length; i < len; i++) {
var m = marks[i];var pair = m.getPairs().get("State");if (pair &&
(pair.value === "Washington" || pair.value === "Oregon")) {onlyWashingtonAndOregon.push(m);
}}return worksheet.selectMarksAsync(
onlyWashingtonAndOregon,tableauSoftware.SelectionUpdateType.REPLACE);
})
.otherwise(function (err) {console.log(err);
});
API Reference
Style and ConventionsTableau's JavaScript API follows these JavaScript standards:
l Classes are PascalCase (initial capital letter, with each subsequent word capitalized)l Namespaces, methods, parameters, and variables are camelCase (initial lower-case letter, with each subsequent word capitalized)
l Constants and enum values are UPPERCASE_UNDERSCORE_DELIMITEDl Protected variables or methods start with an initial underscore '_' character,indicating that it should not be referenced by the programmer.
- 409 -
Top-Level Class DiagramThe following class diagram shows the relationships between the top-level classes, as well asthe inheritance hierarchy for the Sheet, Dashboard, Story and Worksheet classes.Note that there's always a way to traverse back up the containment hierarchywith parentpointers, with the exception of VizManager, as it's a static class and always accessible.
Asynchronous and Error Classes
Promise Class
Represents a promise to return a value from an asynchronousmethod in the future. TheTableau JavaScript API implements the Promises/A specification.
Methods
Name ReturnType
Description
then(callback:Function,errback:Function)
Promise Creates a link in the asynchronous callable chain. Thecallback function is called on success. The errbackfunction is called when there is an error. Both parametersare optional.
always(callback:Function)
Promise Registers a callback that will be called when a promise isresolved or rejected. Shortcut for then(callback,callback).
otherwise(errback:
Promise Registers a rejection handler. Shortcut for then(null,errback).
- 410 -
Function)
TableauException Class
The TableauException class is not a real class, but simply adds an id field to the standardJavaScript Error object when an exception is thrown fromwithin the API. As theprogrammer, this allows you to uniquely identify the error without having to parse the errorstring. It also allows you to add localizedmessages.Constructor
There is no public constructor. The only way to get a reference to a TableauException is withina catch block.Fields
Name Type DescriptiontableauSoftwareErrorCode ErrorCode Represents an ErrorCode enum
value.message string This is already defined on the standard
Error object, but themessage willcontain a description of the exceptionthat the API code specifies.
ErrorCode Enum
Here's a list of the different exceptions that the API can throw:
Name Value DescriptionBROWSER_NOT_CAPABLE
browserNotCapable The browser is not capable ofsupporting the TableauJavaScript API.
DOWNLOAD_WORKBOOK_NOT_ALLOWED
downloadWorkbookNotAllowed The permissions on a workbookor a view do not allowdownloading the workbook.
FILTER_CANNOT_BE_PERFORMED
filterCannotBePerformed An error occurred whileattempting to perform a filteroperation.
INDEX_OUT_OF_RANGE
indexOutOfRange Attempted to switch to a sheetby index that does not exist inthe workbook.
INTERNAL_ERROR
internalError An error occurred within theTableau JavaScript API.Contact Tableau Support.
INVALID_AGGREGATIO-N_FIELD_NAME
invalidAggregationFieldName An invalid aggregation was spe-cified for the filter, such as set-ting a range filter to "SUM(Sales)" instead of "Sales".
- 411 -
INVALID_CUSTOM_VIEW_NAME
invalidCustomViewName An operation was attempted ona custom view that does notexist.
INVALID_DATE_PARAMETER
invalidDateParameter An invalid date was specified inamethod that required a dateparameter.
INVALID_FILTER_FIELDNAME
invalidFilterFieldName A filter operation was attemptedon a field that does not exist inthe data source.
INVALID_FILTER_FIELDNAME_OR_VALUE
invalidFilterFieldNameOrValue Either a filter operation wasattempted on a field that doesnot exist in the data source, orthe value supplied in the filteroperation is the wrong data typeor format.
INVALID_FILTER_FIELDVALUE
invalidFilterFieldValue A filter operation was attemptedusing a value that is the wrongdata type or format.
INVALID_PARAMETER
invalidParameter A parameter is not the correctdata type or format. The nameof the parameter is specified inthe Error.message field.
INVALID_SELECTION_DATE
invalidSelectionDate An invalid date value wasspecified in aSheet.selectMarksAsync() call for a date field.
INVALID_SELECTION_FIELDNAME
invalidSelectionFieldName A field was specified in aSheet.selectMarksAsync() call that does not exist in thedata source.
INVALID_SELECTION_VALUE
invalidSelectionValue An invalid value was specified inaSheet.selectMarksAsync() call.
INVALID_SIZE invalidSize A negative size was specified orthemaxSize value is less thanminSize inSheet.changeSizeAsync().
INVALID_SIZE_BEHAVIOR_ON_WORKSHEET
invalidSizeBehaviorOnWorksheet
A behavior other thanSheetSizeBehavior.AUTOMATIC was specified inSheet.changeSizeAsync() when the sheet is aWorksheet instance.
- 412 -
INVALID_URL invalidUrl The URL specified in the Vizclass constructor is not valid.
MISSING_MAX_SIZE
missingMaxSize The maxSize field ismissing inSheet.changeSizeAsync() when specifyingSheetSizeBehavior.ATMOST.
MISSING_MIN_SIZE
missingMinSize The minSize field ismissing inSheet.changeSizeAsync() when specifyingSheetSizeBehavior.ATLEAST.
MISSING_MINMAX_SIZE
missingMinMaxSize Either or both of the minSizeor maxSize fields ismissing inSheet.changeSizeAsync() when specifyingSheetSizeBehavior.RANGE.
MISSING_RANGEN_FOR_RELATIVE_DATE_FILTERS
missingRangeNForRelativeDateFilters
The rangeN field ismissing fora relative date filter of typeLASTN or NEXTN.
NO_URL_FOR_HIDDEN_WORKSHEET
noUrlForHiddenWorksheet An attempt wasmade to accessSheet.getUrl() on a hiddensheet. Hidden sheets do nothave URLs.
NO_URL_OR_PARENT_ELEMENT_NOT_FOUND
noUrlOrParentElementNotFound
One or both of theparentElement or the URLparameters is not specified inthe Viz constructor.
NOT_ACTIVE_SHEET
notActiveSheet An operation was attempted ona sheet that is not active orembedded within the activedashboard.
NULL_OR_EMPTY_PARAMETER
nullOrEmptyParameter A required parameter was notspecified, null, or an emptystring/array.
SERVER_ERROR
serverError A general-purpose server erroroccurred. Details are containedin the Error object.
SHEET_NOT_IN_WORKBOOK
sheetNotInWorkbook An operation was attempted ona sheet that does not exist in theworkbook.
- 413 -
STALE_DATA_REFERENCE
staleDataReference An operation is performed on aCustomView object that is nolonger valid (it has beenremoved).
UNSUPPORTED_EVENT_NAME
unsupportedEventName An unknown event namewasspecified in the call toViz.addEventListener orViz.removeEventListener.
VIZ_ALREADY_IN_MANAGER
vizAlreadyInManager A Viz object has already beencreated as a child of theparentElement specified inthe Viz constructor.
Viz Classes
VizManager Class
Manages all of the Viz instances on the page, but does not manage vizzes (views) earlier thanversion 8.0. This is a static class, meaning that all properties andmethods are static and thereis only a single instance of the class.Properties
Name Type DescriptiongetVizs() Viz[] Collection of views on the hosting page.
Viz Class
Wraps an <iframe> showing one or more sheets in a Tableau workbook. Contains all of thechrome surrounding the view.Constructor
Signature DescriptionViz(parentElement:domNode, url:string, options:VizCreateOptions)
Creates a new Tableau Viz inside of the given HTMLcontainer, which is typically a <div> element. Each option aswell as the options parameter is optional. If there is already aViz associated with the parentElement, an exception isthrown. Before reusing the parentElement youmust first calldispose().
Properties
Name Type DescriptiongetAreTabsHidden() bool Indicateswhether the tabs are
displayed in the UI. It does notactually hide individual tabs.
- 414 -
getIsToolbarHidden() bool Indicateswhether the toolbar isdisplayed.
getIsHidden() bool Indicateswhether the viz isdisplayed on the hosting page.
getParentElement() domNode Returns the node that wasspecified in the constructor.
getUrl() string The URL of the viz, as specified inthe constructor
getWorkbook() Workbook One Workbook is supported perviz.
getAreAutomaticUpdatesPaused()
bool Indicateswhether automaticupdates are currently paused.
Events
Events are added or removed via the following two calls.
Name ReturnType
Description
addEventListener(type:TableauEventName,listener: Function)
None Adds an event listener to the specified event.
removeEventListener(type:TableauEventName,listener: Function)
None Removes an event listener from thespecified event.
Methods
Name Type Descriptionshow()hide()
None Shows or hides the <iframe>hosting the viz.
dispose() None Cleans up any resources associatedwith the viz, removes the viz from theVizManager, and removes anyDOMelements from parentElement.Basically, it restores the page towhat it was before instantiating anew Viz object.
pauseAutomaticUpdatesAsync()resumeAutomaticUpdatesAsync()toggleAutomaticUpdatesAsync()
None Pauses or resumes layout updates.This is useful if you are resizing theviz or performingmultiple calls thatcould affect the layout.
revertAllAsync() Promise Equivalent to clicking on the RevertAll toolbar button, which restores theworkbook to its starting state.
- 415 -
refreshDataAsync() None Equivalent to clicking on the RefreshData toolbar button.
showDownloadWorkbookDialog()
None Equivalent to clicking on theDownload toolbar button, whichdownloads a copy of the originalworkbook.
showExportImageDialog() None Equivalent to clicking on the ExportImage toolbar button, which createsa PNG file of the current viz.
showExportPDFDialog() None Equivalent to clicking on the ExportPDF toolbar button, which shows adialog allowing the user to selectoptions for the export.
showExportDataDialog( work-sheetInDashboard: Sheet orSheetInfo or string)
None Shows the Export Data dialog, whichis currently a popup window. TheworksheetInDashboard para-meter is optional. If not specified, thecurrently active Worksheet isused.
showExportCrossTabDialog( worksheetInDashboard: Sheetor SheetInfo or string)
None Shows the Export CrossTab dialog.The worksheetInDashboardparameter is optional. If not spe-cified, the currently active Work-sheet is used.
showShareDialog() None Equivalent to clicking on the Sharetoolbar button, which displays adialog allowing the user to share theviz by email or by embedding itsHTML in a web page.
setFrameSize(width: int, height:int)
None Sets the size of the iFrame, whichcauses the viz to expand or collapseto fit the iFrame if the viz’s currentsheet’s size is set to AUTOMATIC.
VizCreateOptions Record
These are the options that are specified in the Viz constructor.Fields
Name Type DescriptionhideTabs bool Indicateswhether tabs are hidden or shown.hideToolbar bool Indicateswhether the toolbar is hidden or
shown.toolbarPosition ToolbarPosition Indicateswhere the toolbar should be placed
if hideToolbar is false.height string Can be any valid CSS size specifier. If not
- 416 -
specified, defaults to 600px.width string Can be any valid CSS size specifier. If not
specified, defaults to 800px.onFirstInteractive callback(e:
TableauEvent)Callbackwhen the viz first becomesinteractive. This is only called once, but it’sguaranteed to be called. If the viz is alreadyinteractive, it will be called immediately, but ona separate "thread."
ToolbarPosition EnumEnumeration
Name DescriptionTOP Positions the toolbar along the top of the viz.BOTTOM Positions the toolbar along the bottom of the viz.
Viz Event Classes
TableauEventName Enum
These are strings passed to Viz.addEventListener/removeEventListener. Note that the valueof the enums are all lowercase stringswith no underscores. For example, CUSTOM_VIEW_LOAD is customviewload. Either the fully-qualified enum(tableauSoftware.TableauEventName.FILTER_CHANGE) or the raw string(filterchange) is acceptable.
Name Event Class Passedin the Callback
Description
CUSTOM_VIEW_LOAD
CustomViewEvent Raised when a custom view hasfinished loading.
CUSTOM_VIEW_REMOVE
CustomViewEvent Raised when the user removes acustom view.
CUSTOM_VIEW_SAVE
CustomViewEvent Raised when the user saves a new orexisting custom view.
CUSTOM_VIEW_SET_DEFAULT
CustomViewEvent Raised when a custom view has beenmade the default view for this viz.
FILTER_CHANGE
FilterEvent Raised when any filter has changedstate. The vizmay not be interactiveyet.
MARKS_SELECTION
MarksEvent Raised whenmarks are selected ordeselected.
PARAMETER_VALUE_CHANGE
ParameterEvent Raised when any parameter haschanged state.
STORY_POINT_SWITCH
StoryPointSwitchEvent Raised after a story point becomes act-ive.
- 417 -
TAB_SWITCH TabSwitchEvent Raised after the tab switched, but thevizmay not yet be interactive.
TableauEvent ClassProperties
Name Type DescriptiongetViz() Viz Gets the Viz object associated with the
event.getEventName()
TableauEventName Gets the name of the event which is a string,but is also one of the items in theTableauEventName enum.
CustomViewEvent ClassProperties
Name Type DescriptiongetViz() Viz Gets the Viz object associated with the
event.getEventName()
TableauEventName Gets the name of the event which is a string,but is also one of the items in theTableauEventName enum.
Methods
Name Return Type DescriptiongetCustomViewAsync()
Promise<CustomView> Gets the CustomView objectassociated with the event.
FilterEvent ClassProperties
Name Type DescriptiongetViz() Viz Gets the Viz object associated with the
event.getWorksheet()
Worksheet Gets the Worksheet object associated withthe event.
getEventName()
TableauEventName Gets the name of the event which is a string,but is also one of the items in theTableauEventName enum.
getFieldName()
string Gets the name of the field.
Methods
Name Return Type DescriptiongetFilterAsync() Promise<Filter> Gets the Filter object associated with the event.
- 418 -
MarksEvent ClassProperties
Name Type DescriptiongetViz() Viz Gets the Viz object associated with the
event.getWorksheet()
Worksheet Gets the Worksheet object associated withthe event.
getEventName()
TableauEventName Gets the name of the event which is a string,but is also one of the items in theTableauEventName enum.
Methods
Name Return Type DescriptiongetMarksAsync()
Promise<Mark[]>
Gets the selectedmarks on the Worksheet thattriggered the event.
ParameterEvent ClassProperties
Name Type DescriptiongetViz() Viz Gets the Viz object associated with the
event.getEventName() TableauEventName Gets the name of the event which is a
string, but is also one of the items in theTableauEventName enum.
getParameterName()
string Gets the name of the parameter thatchanged.
Methods
Name Return Type DescriptiongetParameterAsync()
Promise<Parameter> Gets the Parameter object thattriggered the event.
StoryPointSwitchEvent Class
Returned in the callback for the STORY_POINT_SWITCH event.Properties
Name Type DescriptiongetViz() Viz Gets the Viz object associated with
the event.getEventName() TableauEventName Gets the name of the event which is a
string, but is also one of the items inthe TableauEventName enum. In thiscase, it is STORY_POINT_SWITCH.
- 419 -
getOldStoryPointInfo()
StoryPointInfo Gets the StoryPointInfo thatwas active before the story pointswitch event occurred. The returnedobject reflects the state of the storypoint before the switch occurred. Thereturned object reflects the state ofthe story point after the switchoccured.
getNewStoryPoint() StoryPoint Gets the StoryPoint that is cur-rently active.
TabSwitchEvent ClassProperties
Name Type DescriptiongetViz() Viz Gets the Viz object associated with the
event.getEventName() TableauEventName Gets the name of the event which is a
string, but is also one of the items in theTableauEventName enum.
getOldSheetName()
string Gets the name of the sheet that wasactive before the tab switch eventoccurred.
getNewSheetName()
string Gets the name of the sheet that iscurrently active.
- 420 -
Workbook Classes
Class Diagram
Workbook Class
AWorkbook has a collection of Sheets represented as tabs. It also has associated objects likeDataSources and CustomViews.Properties
Name Type DescriptiongetViz() Viz Gets the Viz object that contains the
workbook.getActiveSheet() Sheet Gets the currently active sheet (the active
tab)getActiveCustomView() CustomView Gets the currently active custom view, or
null if no custom view is active.getPublishedSheetsInfo()
SheetInfo[] Note that this is synchronous, meaningthat all of the sheets are expected whenloaded.
getName() string Gets the name of the workbook saved tothe server. Note that this is notnecessarily the file name.
Methods
Name Return Type DescriptionactivateSheetAsync(sheetNameOrIndex: object)
Promise<Sheet> Activates the sheet,either by name or index,and returns a promise ofthe sheet that was activ-
- 421 -
ated.revertAllAsync() Promise Reverts the workbook to
its last saved state.getParametersAsync() Promise<Paramete
r[]>Fetches the parametersfor this workbook.
changeParameterValueAsync(name: string,value: object)
Promise<Parameter>
Changes the value of theparameter with the givenname and returns thenew Parameter. Thevalue should be the samedata type as theparameter and within theallowable range ofvalues. It also needs tobe the aliased value andnot the raw value. Formore information andexamples, seechangeParameterValueAsync() AdditionalInformation
getCustomViewsAsync() Promise<CustomView[]>
Gets the collection ofCustomView objectsassociated with the work-book.
showCustomViewAsync(customViewName: string)
Promise<CustomView>
Changes the viz to showthe named saved state.
removeCustomViewAsync(customViewName: string)
Promise<CustomView>
Removes the namedcustom view.
rememberCustomViewAsync(customViewName: string)
Prom-ise<CustomView>
Remembers the currentstate of the workbook byassigning a custom viewname.
setActiveCustomViewAsDefaultAsync()
None Sets the active customview as the default.
changeParameterValueAsync() Additional Information
The value parameter needs tomeet the following conditions:
1. The data type should be the same underlying JavaScript type as is returned in Para-meter.getCurrentValue(). For example, if Parameter.getDataType() isFLOAT or INTEGER, the value parameter should be a native JavaScript Number. Thefollowing tablemaps the ParameterDataType values to native JavaScript types.
ParameterDataType Native JavaScript Type
- 422 -
FLOAT NumberINTEGER NumberSTRING StringBOOLEAN BooleanDATE DateDATETIME Date
2. If the parameter is restricted to a list of allowable values, the value should be one ofthose values. Querying Parameter.getAllowableValuesType() will indicate ifthe parameter values are restricted by returning tableau-Software.ParameterAllowableValuesType.LIST.
3. If the parameter is restricted to a range of values, the value should be within themin-imum andmaximum values, inclusive. Querying Para-meter.getAllowableValuesType() will indicate if the parameter values arerestricted by returning tableau-Software.ParameterAllowableValuesType.RANGE. Theminimumandmax-imum values are returned via Parameter.getMinValue() andParameter.getMaxValue().
4. The value needs to be the aliased value, and not the raw value. To view the raw andaliased values, go to theEdit Parameter dialog box inTableau Desktop. In that dialog,use the values in theDisplay As column and not theValue column, as shown below.
- 423 -
Examples
The following exampleswill help illustrate these concepts.
// Change a parameter called "Prouct Type" to "Coffee" when theparameter is
// restricted to the following allowable values:
// "Coffee", "Espresso", "Tea"
workbook.changeParameterValueAsync("Product Type", "Coffee");
// Change a parameter called "Measure" to a value that isaliased, "Sale". This
// example corresponds to the screen shot above.
workbook.changeParameterValueAsync("Measure", "Sale");
// Change a date parameter named "DateParam" to January 1, 2014(UTC):
workbook.changeParameterValueAsync("DateParam", new Date(Date.UTC(2014, 0, 1)));
DataSource Class
The Workbook contains one or more data sources. Each Worksheet will have a primarydata source and can havemultiple secondary data sources.Properties
Name Type DescriptiongetName() string The name of the DataSource as seen in the UI.getIsPrimary()
bool Indicateswhether this DataSource is a primary or asecondary data source.
getFields() Field[]
Gets an array of Fields associated with the DataSource.
Field Class
A field contains information about what data source it belongs to, its role, and the ability to fetchthe domain values.Properties
Name Type DescriptiongetName() string Gets the field name (i.e. caption).getAggregation()
FieldAggregationType Gets the type of aggregation, which isone of the following values: SUM, AVG,MIN, MAX, STDEV, STDEVP, VAR,VARP, COUNT, COUNTD, MEDIAN,ATTR, NONE, YEAR, QTR, MONTH, DAY,HOUR, MINUTE, SECOND, WEEK,
- 424 -
WEEKDAY, MONTHYEAR, MDY, END,TRUNC_YEAR, TRUNC_QTR, TRUNC_MONTH, TRUNC_WEEK, TRUNC_DAY,TRUNC_HOUR, TRUNC_MINUTE,TRUNC_SECOND, QUART1, QUART3,SKEWNESS, KURTOSIS, INOUT, USER
getDataSource()
DataSource Gets the data source to which this fieldbelongs.
getRole() FieldRoleType One of the following values: DIMENSION,MEASURE, UKNOWN
CustomView Class
Represents a named snapshot of the workbook at a specificmoment.Properties
Name Type DescriptiongetName()setName()
string User-friendly name for the custom view
getAdvertised()setAdvertised()
bool Indicateswhether the custom view is public or private.
getDefault() bool Gets or sets whether this is the default custom view.getOwnerName()
string Gets the user that created the custom view.
getUrl() string Unique URL to load this view again.getWorkbook() Workbook Gets the Workbook to which this CustomView
belongs.Methods
Name Return Type DescriptionsaveAsync()
Promise<CustomView> After saveAsync() is called, the result ofthe getUrlmethod is no longer blank.
- 425 -
Sheet Classes
Class Diagram
SheetInfo Class
Contains information about a WORKSHEET, a DASHBOARD, or a STORY and nomethods.Returned as part of Workbook.getPublishedSheetsInfo().Constructor
There is no public constructor. You can only get instances of this class fromWorkbook.getPublishedSheetsInfo().Properties
Name Type DescriptiongetName() string Gets the name of the sheet.getIndex() int Gets the index of the sheet within the published tabs.
Note that hidden tabs are still counted in the ordering,as long as they are published.
getIsActive() bool Gets a value indicating whether the sheet is thecurrently active sheet.Due to a technical limitation, thiswill always return false if the object is a Worksheetinstance that is part of a Dashboard.
getIsHidden() bool Gets a value indicating whether the sheet is hidden inthe UI. Note that if the entire tab control is hidden, itdoes not affect the state of this flag. This sheet may stillreport that it is visible even when the tabs control ishidden.
getSheetType()
SheetType Gets the type of the sheet. SheetType is an enumwith the following values: WORKSHEET, DASHBOARDand STORY.
getSize() SheetSize Gets the size information that the author specifiedwhen publishing the workbook.
getUrl() string Gets the URL for this sheet.
- 426 -
getWorkbook()
Workbook Gets the Workbook to which this Sheet belongs.
Sheet ClassConstructor
There is no public constructor. You can only get instances of this class fromWorkbook.getActiveSheet()or Dashboard.getObjects().Properties
Name Type DescriptiongetName() string Gets the name of the sheet.getIndex() int Gets the index of the sheet within the published tabs.
Note that hidden tabs are still counted in the ordering,as long as they are published.
getIsActive() bool Gets a value indicating whether the sheet is thecurrently active sheet.
getIsHidden() bool Gets a value indicating whether the sheet is hidden inthe UI. Note that if the entire tab control is hidden, itdoes not affect the state of this flag. This sheet may stillreport that it is visible even when the tabs control ishidden.
getSheetType()
SheetType Gets the type of the sheet. SheetType is an enumwith the following values: WORKSHEET , DASHBOARDand STORY.
getSize() SheetSize Gets the size information that the author specifiedwhen publishing the workbook.
getUrl() string Gets the URL for this sheet.getWorkbook()
Workbook Gets the Workbook to which this Sheet belongs.
Methods
Name Return Type DescriptionchangeSizeAsync(size: SheetSize)
Promise<SheetSize> Sets the size information on a sheet.Note that if the sheet is a Worksheet,onlySheetSizeBehavior.AUTOMATICis allowed since you can’t actually set aWorksheet to a fixed size.
SheetSize Record
Describes the way a Sheet should be sized.Fields
Name Type Descriptionbehavior SheetSizeBehavior Contains an enumeration value of one of the
- 427 -
following: AUTOMATIC, EXACTLY, RANGE,ATLEAST, and ATMOST.
maxSize SheetSize This is only defined when behavior is EXACTLY,RANGE or ATMOST.
minSize SheetSize This is only defined when behavior is EXACTLY,RANGE, or ATLEAST.
Worksheet Class
Represents a worksheet tab in the workbook or a dashboard object. These are two separateconcepts: a worksheet and a worksheet instance. However, for simplicity in the API, they areboth combined into the Worksheet class.Constructor
There is no public constructor. You can only get instances of this class fromWorkbook.getPublishedSheets() or Dashboard.getObjects().Properties
Name Type DescriptiongetParentDashboard()
Dashboard Returns the Dashboard object to which thisWorksheet belongs (if it’s on a dashboard).Otherwise, it returns null.
getParentStoryPoint()
StoryPoint Returns the StoryPoint object to which thisWorksheet belongs (if it’s on a story sheet).Otherwise, it returns null. If the Worksheetinstance does not come from a call toStoryPoint.getContainedSheet(), italso returns null.
Methods
Name Return Type DescriptiongetDataSourcesAsync()
Promise<DataSource[]>
Gets the primary and all of thesecondary data sources for thisworksheet. Note that byconvention the primary datasource should always be the firstelement.
Filteringmethods are described inAPI Reference on page 408. Marks selectionmethods aredescribed inWorksheet Class (SelectingMarks).
Dashboard Class
Contains a collection of DashboardObject instances and a notion of the active object.Constructor
There is no constructor. You get an instance of this fromWorkbook.getPublishedSheets().
- 428 -
Properties
Name Type DescriptiongetObjects() DashboardO
bject[]Gets the collection of objects.
getWorksheets()
Worksheet[] Gets the collection of worksheets contained in thedashboard. Note that this is a helper method andis equivalent to looping through getObjects()and collecting all of theDashboardObject.Worksheet pointerswhen DashboardObject.getType() ===tableauSoftware.DashboardObjectType.WORKSHEET.
getPar-entStoryPoint()
StoryPoint Returns the StoryPoint object to which thisDashboard belongs (if it’s on a story sheet).Otherwise, it returns null. If the Dashboardinstance does not come from a call toStoryPoint.getContainedSheet(), it alsoreturns null.
DashboardObject Class
Represents one of a series of different areas of the dashboard.Constructor
There is no constructor. You get an instance of this from Dashboard.getObjects().Properties
Name Type DescriptiongetObjectType()
DashboardObjectType Gets what the object represents, which isan enum with the following values:BLANK, WORKSHEET, QUICK_FILTER,PARAMETER_CONTROL, PAGE_FILTER, LEGEND, TITLE, TEXT,IMAGE, WEB_PAGE.
getDashboard()
Dashboard Gets the Dashboard object that containsthis object.
getWorksheet()
Worksheet If getType() returns WORKSHEET, thiscontains a pointer to the Worksheetobject.
getPosition() Point Gets the coordinates relative to the top-leftcorner of the dashboard of the object.
getSize() Size Gets the size of the object.
Story Class
Contains a collection of StoryPoint instances and the ability to switch between them. Derivesfrom the Sheet class.
- 429 -
Constructor
There is no constructor. You get an instance of this from Workbook.getActiveSheet().Properties (Derived from Sheet)
Name Type DescriptiongetName() string Gets the name of the sheet.getIndex() int Gets the index of the sheet within the published tabs.
Note that hidden tabs are still counted in the ordering,as long as they are published.
getIsActive() bool Gets a value indicating whether the sheet is thecurrently active sheet.
getIsHidden() bool Gets a value indicating whether the sheet is hidden inthe UI. Note that if the entire tab control is hidden, itdoes not affect the state of this flag. This sheet may stillreport that it is visible even when the tabs control ishidden.
getSheetType()
SheetType Gets the type of the sheet, which should always betableauSoftware.SheetType.STORY.
getSize() SheetSize Gets the size information that the author specifiedwhen publishing the workbook.
getUrl() string Gets the URL for this sheet.getWorkbook()
Workbook Gets theWorkbook to which this Sheet belongs.
Properties
Name Type DescriptiongetStoryPointsInfo()
StoryPointInfo[]
Gets an array (not a collection) ofStoryPointInfo objects. Note that this isnot a collection, since we don’t have aunique string key for a story point. We onlyneed ordinal access to the story points (byindex).
getActiveStoryPoint()
StoryPoint Gets the currently active story point.
Methods (Derived from Sheet)
Name Type DescriptionchangeSizeAsync(size:SheetSize)
Promise<SheetSize> Sets the size information ona sheet.
Methods
Name Type DescriptionactivateStoryPointAsync(index: int)
Promise<StoryPoint>
Activates the story point at thespecified index and returns apromise of the activated StoryPoint.Throws a
- 430 -
tableauSoftware.ErrorCode.INDEX_OUT_OF_RANGE errorif the index is less than zero orgreater than or equal to the numberof story points in the array.
activ-ateNextStoryPointAsync()
Prom-ise<StoryPoint>
Activates the next story point ifthere is one. If the current storypoint is the last one, then is staysactive.
activ-atePre-viousStoryPointAsync()
Prom-ise<StoryPoint>
Activates the previous story point ifthere is one. If the current storypoint is the first one, then it stays act-ive.
revertStoryPointAsync(index: int)
Prom-ise<StoryPoint>
Reverts the story point at the spe-cified index and returns a promiseof the reverted StoryPoint. Throwsa tableau-Soft-ware.ErrorCode.INDEX_OUT_OF_RANGE error if the indexis less than zero or greater than orequal to the number of story pointsin the array.
StoryPointInfoClass
Contains information about a StoryPoint with nomethods. Returned as part ofStory.getStoryPointsInfo().Properties
Name Type DescriptiongetIndex() int Gets the zero-based index of this story point within the
parent Story sheet.getCaption() string Gets the content of the textual description for this story
point.getIsActive() Bool Gets a value indicating whether the story point is the cur-
rently active point in the story.getIsUpdated() Bool Gets a value indicating whether the story point is updated,
meaning that there are no changes from the last time thestory point was “captured”.
getParentStory()
Story Gets the Story object that contains the story point.
StoryPoint Class
A StoryPoint is a distinct snapshot within a Story sheet.
- 431 -
Properties
Name Type DescriptiongetIndex() int Gets the zero-based index of this story point within the
parent Story sheet.getCaption() string Gets the content of the textual description for this story
point.getIsActive() Bool Gets a value indicating whether the story point is the
currently active point in the story.getIsUpdated() Bool Gets a value indicating whether the story point is
updated, meaning that there are no changes from thelast time the story point was “captured”.
getContainedSheet()
Sheet Gets the sheet that this story point contains. This willbe null if the story point does not have a containedsheet.
getParentStory() Story Gets the Story object that contains this story point.
Parameter Classes
Parameter Class
Contains information about a workbook parameter. To actually set a parameter’s value, callworkbook.changeParameterValueAsync().Properties
Name Type DescriptiongetName() string A unique identifier for the
parameter, as specified bythe user.
getCurrentValue() DataValue The current value of theparameter.
getDataType() ParameterDataType The data type of theparameter can be one of thefollowing: FLOAT,INTEGER, STRING,BOOLEAN, DATE,DATETIME.
getAllowableValuesType()
ParameterAllowableValuesType
The type of allowablevalues that the parametercan accept. It can be one ofthe following enumerationitems: ALL, LIST, RANGE.
getAllowableValues() DataValue[] If the parameter is restrictedto a list of allowable values,this property contains the
- 432 -
array of those values. Notethat this is not a standardcollection, but a JavaScriptarray.
getMinValue() DataValue IfgetAllowableValuesType is RANGE, this definestheminimumallowablevalue, inclusive. Otherwiseit’s undefined/null.
getMaxValue() DataValue IfgetAllowableValuesType is RANGE, this definesthemaximumallowablevalue, inclusive. Otherwiseit’s undefined/null.
getStepSize() Number IfgetAllowableValuesType is RANGE, this definesthe step size used in theparameter UI control slider.Otherwise it’sundefined/null.
getDateStepPeriod() PeriodType IfgetAllowableValuesType is RANGE andgetDataType is DATE orDATETIME, this defines thestep date period used in theParameter UI control slider.Otherwise it’sundefined/null.
FilteringThere is a difference between querying existing filter state and setting new or existing filters.Querying filters is done via Worksheet.getFiltersAsync() which returns a collection ofFilter classes. Setting filters is done via Worksheet.applyFilterAsync (and itsvariants) and is a function call that doesn't require you to instantiate a Filter class.
When you specify fields in a filter, you should use the caption as shown in the UI, not thedatabase field name. For example, useContainer (the caption) instead of ProductContainer (the actual field name). The exception is hierarchical filters, which use the fullhierarchical name (for example, [Product].[All Product].[Espresso]). Captionscan use the optional [] delimiters around names.
- 433 -
Class Diagram
Worksheet Class (Filtering)
Thesemethods are on the Worksheet class, but are listed here for convenience.Methods
Name Return Type DescriptiongetFiltersAsync() Promise<Filter[]
>Fetches the collection of filtersused on the sheet.
applyFilterAsync(fieldName: string,values: object[] or object,updateType:FilterUpdateType,options?: FilterOptions)
Promise<string>
Applies a simple categoricalfilter (non-date). See the filteringexamples for more details onthese functions. Returns thefieldName that was filtered.
applyRangeFilterAsync(fieldName: string,range: RangeFilterOptions)
Promise<string>
Applies a quantitative filter. If arange is specified that is outsideof the domainmin/max values,no error is raised and thecommand is allowed.Subsequent calls togetFiltersAsync[] willreturn these values even if theyare outside of the bounds of thedomain. This is equivalent to thebehavior in Tableau Desktop.
- 434 -
applyRel-ativeDateFilterAsync(fieldName: string,options: Rel-ativeDateFilterOptions)
Prom-ise<string>
Applies a relative date filter.
applyHierarchicalFilterAsync(fieldName: string,values: object,options: Hier-archicalFilterOptions)
Prom-ise<string>
Applies a hierarchical filter. Thevalues parameter is either asingle value, an array of values,or an object { levels: ["1", "2"] }.
clearFilterAsync(fieldName:string)
Prom-ise<string>
Clears the filter, nomatter whatkind of filter it is. Note that the fil-ter is removed as long as noassociated quick filter is showingfor the field. If there is a quick fil-ter showing, then the filter iskept, but it’s reset to the “All”state (effectually canceling the fil-ter). For relative date filters, how-ever, an error is returned sincethere is no “All” state for a rel-ative date filter. To clear a rel-ative date filter with a quick filtershowing, you can callapplyRel-ativeDateFilter() insteadusing a range that makes sensefor the specific field.
FilterOptions Record
Passed into the applyFiltermethods to control advanced filtering options.Fields
Name Type DescriptionisExcludeMode bool Determineswhether the
filter will apply in excludemode or includemode. Thedefault is include, whichmeans that you use thefields as part of a filter.Excludemodemeans thatyou include everything elseexcept the specified fields.
- 435 -
RangeFilterOptions Record
Passed into the applyRangeFilterAsyncmethod to control advanced filtering options.Fields
Name Type Descriptionmin int Minimum value for the range
(inclusive). Optional. Leaveblank if you want a <= filter.
max int Maximum value for therange (inclusive). Optional.Leave blank if you want a >=filter.
nullOption NullOption The null values to include.
RelativeDateFilterOptions Record
Passed into the applyRelativeDateFilterAsyncmethod to control advanced filteringoptions.Fields
Name Type DescriptionanchorDate Date The UTC date fromwhich to filter.periodType PeriodType Year, quarter, month, etc.rangeType DateRangeType LAST, LASTN, NEXT, etc.rangeN int The number used when the rangeType is LASTN
or NEXTN.
Filter Class
An abstract base class for all of the various filter types.Properties
Name Type DescriptiongetWorksheet()
Worksheet Gets the parent worksheet
getFilterType()
FilterType Gets the type of the filter. See FilterType Enum for thevalues in the enum.
getFieldName()
string Gets the name of the field being filtered. Note that thisis the caption as shown in the UI and not the actualdatabase field name.
Methods
Name Return Type DescriptiongetFieldAsync() Promise<Field> Gets the field that is currently being filtered.
- 436 -
NullOption Enum
An enumeration that indicateswhat to do with null values for a given filter or mark selection call.Enumeration
Name DescriptionNULL_VALUES Only include null values in the filter.NON_NULL_VALUES Only include non-null values in the filter.ALL_VALUES Include null and non-null values in the filter.
CategoricalFilter ClassProperties
Name Type DescriptiongetIsExcludeMode()
bool Gets a value indicating whether the filter is excludeor include (default).
getAppliedValues()
DataValue[]
Gets the collection of values that are currently seton the filter. Note that this is a native JavaScriptarray and not a keyed collection.
QuantitativeFilter ClassProperties
Name Type DescriptiongetDomainMin() DataValue Gets theminimum value as specified in the
domain.getDomainMax() DataValue Gets themaximum value as specified in the
domain.getMin() DataValue Gets theminimum value, inclusive, applied to
the filter.getMax() DataValue Gets themaximum value, inclusive, applied to
the filter.getIncludeNullValues()
bool Indicateswhether null values are included inthe filter.
RelativeDateFilter ClassProperties
Name Type DescriptiongetPeriod() PeriodType The date period of the filter. See PeriodType Enum
for the values in the enum.getRange() DateRangeType The range of the date filter (years, months, etc.).
See DateRangeType Enum for the values in theenum.
getRangeN()
int When getRange returns LASTN or NEXTN, this isthe N value (how many years, months, etc.).
- 437 -
DataValue Record
A DataValue contains both the raw and formatted value for a filter or parameter. Date valuesare always expressed in UTC dates.Fields
Name Type Descriptionvalue object Contains the raw native value as a JavaScript type, which
is one of String, Number, Boolean, or DateformattedValue string The value formatted according to the locale and the
formatting applied to the field or parameter.
FilterType Enum
An enumeration of the valid types of filters that can be applied.Enumeration
Name DescriptionCATEGORICAL Categorical filters are used to filter to a set of valueswithin the
domain.QUANTITATIVE Quantitative filters are used to filter to a range of values from a
continuous domain.HIERARCHICAL Hierarchical filters are used to filter to a set of values organized
into a hierarchywithin the domain.RELATIVE_DATE
Relative date filters are used to filter a date/time domain to arange of values relative to a fixed point in time.
FilterUpdateType Enum
An enumeration of the valid types of filtering that can be done.Enumeration
Name DescriptionALL Adds all values to the filter. Equivalent to checking the (All) value in a
quick filter.REPLACE Replaces the current filter valueswith new ones specified in the call.ADD Adds the filter values as specified in the call to the current filter values.
Equivalent to checking a value in a quick filter.REMOVE Removes the filter values as specified in the call from the current filter
values. Equivalent to unchecking a value in a quick filter.
PeriodType Enum
An enumeration of a date period used in filters and in parameters.Enumeration
NameYEARS
- 438 -
QUARTERSMONTHSWEEKSDAYSHOURSMINUTESSECONDS
DateRangeType Enum
An enumeration of the valid date ranges for a relative date filter.Enumeration
Name DescriptionLAST Refers to the last day, week, month, etc. of the date period.LASTN Refers to the last N days, weeks, months, etc. of the date period.NEXT Refers to the next day, week, month, etc. of the date period.NEXTN Refers to the next N days, weeks, months, etc. of the date period.CURRENT Refers to the current day, week, month, etc. of the date period.TODATE Refers to everything up to and including the current day, week, month,
etc. of the date period.
Marks SelectionSelectingmarks is almost identical to filtering. For filtering, you use one of theWorksheet.applyFilterAsync()methods. For selectingmarks, you useWorksheet.selectMarksAsync(). The parameters for marks selection are almostidentical to those used for filtering.This provides a very simple, easy to learn, and consistentway to accomplish the twomost common use cases for the API: filtering and selection.
Worksheet Class (Selecting Marks)
Thesemethods are on the Worksheet class, but are shown here for convenience.Methods
Name Return Type DescriptionclearSelectedMarksAsync()
void Clears the selection for thisworksheet.
getSelectedMarksAsync() Promise<Mark[]>
Gets the collection of marks that arecurrently selected.
selectMarksAsync(fieldName: string,value: object or object[],updateType:SelectionUpdateType)
void Selects themarks and returns them.
selectMarksAsync( void Allows selection based on this syntax
- 439 -
fieldValuesMap: object,updateType:SelectionUpdateType)
for the first parameter:{"Field1": value,"Field2": [1, 2, 3]}
selectMarksAsync(marks: Mark[],updateType:SelectionUpdateType)
void
Mark Class
Amark represents a single data point on the viz. It is independent of the type of viz (bar, line,pie, etc.).Constructor
Signature DescriptionMark(pairs: Pair[]) Creates a new Mark with the specified pairs.
Properties
Name Type DescriptiongetPairs()
Pair[] Gets a collection of field name/value pairs associated with themark.
Pair Class
A pair contains a field name and a value (both the raw and formatted values).Constructor
Signature DescriptionPair(fieldName: string, value:object)
Creates a new Pair with the specified fieldname/value pairing
Fields
Name Type DescriptionfieldName string The field name to which the value is applied.value object Contains the raw native value for the field as a JavaScript
type, which is one of String, Number, Boolean, or Date.formattedValue string The value formatted according to the locale and the
formatting applied to the field.
SelectionUpdateType Enum
An enumeration of the valid types of marks selection that can be done.Enumeration
Name Description
- 440 -
REPLACE Replaces the current marks valueswith new ones specified in the call.ADD Adds the values as specified in the call to the current selection.
Equivalent to control-clicking in desktop.REMOVE Removes the values as specified in the call from the current selection.
Equivalent to control-clicking an already selectedmark in desktop.
Other Classes
Size Record
Represents a width and height in pixels. This is implemented as a plain JavaScript object (it’snot a class).Fields
Name Type Descriptionwidth int Expressed in pixel units.height int Expressed in pixel units.
Point Record
Represents an x/y coordinate in pixels. This is implemented as a plain JavaScript object (it’s nota class).Fields
Name Type Descriptionx int Expressed in pixel units.y int Expressed in pixel units.
- 441 -
REST APIWith the Tableau Server REST API you canmanage and change Tableau Server resourcesprogrammatically, via HTTP. The API gives you simple access to the functionality behind thedata sources, projects, workbooks, site users, and sites on a Tableau server. You can use thisaccess to create your own custom applications or to script interactionswith Tableau Serverresources. See the topics below for more information:
RequirementsHere are the requirements for using the Tableau Server REST API:
l Tableau Server version: To programwith the REST API, you need Tableau Serverversion 8.2 or higher.
l API enabled: By default, Tableau Server installs with the REST API disabled. Beforeyou can use the API, enable it using the procedure below.
l Application Server process: The server must be running at least one applicationserver (wgserver.exe) process. For information about configuring server processes, seeReconfigure Processes on page 23.
Enabling the REST APIAfter you install Tableau Server, enable the REST API by doing the following:
1. On the computer running Tableau Server, open a command prompt as an administratorand navigate to Tableau Server’s bin directory. For example:
Program Files\Tableau\Tableau Server\8.2\bin
2. Stop Tableau Server.
tabadmin stop
3. Enter the following command to enable the API:
tabadmin set api.server.enabled true
4. Propagate the change:
tabadmin configure
5. Start Tableau Server.
tabadmin start
The application code you create can be located on any computer, as long as it canmakeHTTP requests against the computer that’s running Tableau Server.
- 442 -
ConceptsThis topic is designed for people who are familiar with REST APIs and with using TableauServer.
Components of a CallA Tableau Server REST API call consists of the following:
l HTTP method: There are four methods: GET, POST, PUT, or DELETE.l Tableau Server URI: The URI is the server resource being acted upon.l Parameter: The URI may contain one or more parameters.l Message payload: POST and PUT calls usually require an XMLmessage payload,which contains inputs or additions to the server. GET and DELETE calls do not require amessage payload.
Using theQuery Datasources call as an example (GET /api/2.0/sites/site-id/datasources), here are the components:
l HTTP method: GETl Tableau Server URI: /api/2.0/sites/site-id/datasourcesl Parameter: site-id. It uniquely identifies the site to Tableau Server.l Message payload: None. Because you are not providing an input or adding to TableauServer resources, there is nomessage payload for this call.
In response to the above call, Tableau Server returns two things: a status code and a responsepayload.
The status code, such as 200 (success), is a standard HTTP return value. For each call in theREST API Reference, all possible error codes are listed. The response payload returnswhatyou requested as an XMLmessage. For the above call, the response payload would be a list ofdata sources for the site. The reference lists every call’s response payload. See XMLSchemafor more details.
Signing InThe Tableau Server REST API requires an authentication token to be sent with each API call.The token should be sent with all requests as the header X-Tableau-Auth. For example:
Content-Type: text/xmlX-Tableau-Auth: d14a028c2a3a2bc9476102bb288234c4
You can retrieve a token by completing a Sign In call and parsing the token out of the responsepayload. The token should be stored in your application logic and reused until the session ends.Sample code is provided in the file example.py. It demonstrates how tomake a Sign In call andparse the returned token.
A SignOut call ends the session and invalidates the token.
- 443 -
XML SchemaSomeAPI calls return a response payload for the requested resource, in XML. The responsepayload can be parsed and used within the application logic of your code.
An XML schema for the entire API is in the file ts-rest-api.xsd. API calls that require an XMLresponse payload require that XML to be well-formed and to conform to the schema in ts-rest-api.xsd.
LUIDsLUIDs (Locally Unique Identifiers) are used throughout the REST API to identify resources onTableau Server. LUIDs are 32-character strings separated by dashes in the format'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'. The IDs are returned by certain querymethods, and can be chained with additional calls to act on the resource. For example, user-idcan be retrieved by issuing aGet Users on Site call and parsing out the desired user and user-id. User-id is not the user name, and site-id is not the id used in the Tableau Server userinterface.
Sample and SchemaTo help you use the REST API, Tableau provides two files.
Sample code file: The code in the file example.py demonstrates how to use the REST API tomake a Sign In call and parse the returned token.
XML schema file: The XML schema for the entire REST API is in the file ts-api.xsd.
API ReferenceWith the Tableau Server REST API you canmanage and change Tableau Server resourcesprogrammatically, via HTTP. The API gives you simple access to the functionality behind thedata sources, projects, workbooks, site users, and sites on a Tableau server. You can use thisaccess to create your own custom applications or to script interactionswith Tableau Serverresources.
Before you can use the Tableau Server REST API, youmust enable it. See Enabling the APIfor steps.
Sign In
Sign In as a Tableau Server Administrator
Descrip-tion
Signs you in as the Tableau Server system administrator. For productionenvironments, it's recommended that you sign in via HTTPS.
Methodand URI
POST /api/2.0/auth/signin
- 444 -
MessagePayload
<tsRequest><credentials name="admin-username" password="admin-pass-
word" ><site contentUrl="target-site-content-URL" />
</credentials></tsRequest>
ResponseCode
200
ResponsePayload
<tsResponse><credentials token="admin-user-authenticity-token" >
<site contentUrl="target-site-content-URL" /></credentials>
</tsResponse>
Sign In as a Tableau Server User
Descrip-tion
Signs you in as a Tableau Server user. For production environments, it'srecommended that you sign in via HTTPS.
Methodand URI
POST /api/2.0/auth/signin
MessagePayload
<tsRequest><credentials name="admin-username" password="admin-pass-
word" ><site contentUrl="target-site-content-URL" /><user id="user-to-run-as" />
</credentials></tsRequest>
ResponseCode
200
ResponsePayload
<tsResponse><credentials token="run-as-user-token" >
<site contentUrl="target-site-content-URL" /></credentials>
</tsResponse>
Payload Details
The name and password in the credentials element must represent a user who hasadministrative permissions on the server and on the specified site.
Note: If the server is configured to use Active Directory authentication, and if the username is not unique across domains, youmust include the domain as part of the username (for example, example\Adam).
- 445 -
The <site> element is required in the request to specify the site that the user will be loggedinto. When the <site> element is empty in the request, the default site will be used:
<site />
The default site can also be specified using empty quotes:
<site contentUrl="" />
The <site> element is always populated in the response.
Error Conditions
HTTP Response Code Condition Details401 Login error The name or
password isinvalid for thegiven site, or thesite content URLis invalid.
403 Non-admin sign-in forbidden An attempt wasmade to sign in auser (non-admin-istrator) directly,using the user’scredentials. ATableau Serveruser can besigned in only indir-ectly via an admin-istrator’scredentials.
404 User not found The user ID givenin the payload fora user sign-indoes not cor-respond to anexisting user onthe site.
405 Invalid request method Request type wassomething otherthan a POST.
- 446 -
Sign OutDescription Signs you out of the current session and invalidates the token.
Method and URI POST /api/2.0/auth/signout
Message Payload NoneResponse Code 204Response Payload None
Error Conditions
HTTP Response Code Condition Details405 Invalid request method Request type was
something otherthan a POST.
Query DatasourcesDescription Returns a list of data sources on the specified site, with optional parameters
for specifying the paging of large results.
Method and URI GET /api/2.0/sites/site-id/datasources
GET /api/2.0/sites/site-id/datasources?pageSize=page-size&pageNumber=page-number
Message Pay-load
None
Response Code 200Response Pay-load
<tsResponse><pagination pageNumber="pageNumber"
pageSize="page-size"totalAvailable="total-available" />
<datasources><datasource id="datasource1-id"
name="datasource1-name"type="datasource1-type" ><project id="project-id" name="project-name" /><tags>
- 447 -
<tag label="tag1"/><tag label="tag2"/>... more tags ...
</tags></datasource><datasource id="datasource2-id"
name="datasource2-name"type="datasource2-type" ><project id="project-id" name="project-name" /><tags>
<tag label="tag3"/>... more tags ...
</tags></datasource>... more datasources ...
</datasources></tsResponse>
Business Logic and Error ConditionsNon-Administrator User Access
Tableau Server users who are not administrators can access this API method, but they canonly view data sources for which they have theConnect capability allowed (either explicitly orimplicitly).Pagination Parameter Defaults
By default the page size is 100 and page 1 is served. One or both parameters can beoverridden explicitly.Error Conditions
HTTP Response Code Condition Details400 Invalid page size The page size parameter is not
an integer, or is less than one.400 Invalid page number The page number parameter is
not an integer, is less than one,or is greater than the final pagenumber for data sources at therequested page size.
404 Site not found The site ID given in the URIdoes not correspond to anexisting site.
405 Invalid request method Request type was somethingother than a GET.
- 448 -
Query DatasourceDescription Returnsmetadata about a specific data source.
Method and URI GET /api/2.0/sites/site-id/datasources/datasource-id
Message Payload NoneResponse Code 200Response Payload <tsResponse>
<datasource id="datasource-id"name="some-name"type="some-type" ><project id="project-id" name="project-name" /><tags>
<tag label="tag1"/><tag label="tag2"/>... more tags ...
</tags></datasource>
</tsResponse>
Business Logic and Error ConditionsNon-Administrator User Access
Tableau Server users who are not administrators can access this API method, but they canonly view data sources for which they have theConnect capability allowed (either explicitly orimplicitly).Error Conditions
Condition HTTP Response Code Details403 Read forbidden A non-administrator user
invoked the API method andattempted to query a datasource for which he or shedid not have theConnectcapability allowed.
404 Site not found The site ID given in the URIdoes not correspond to anexisting site.
404 Data source not found The data source ID given inthe URI does not correspondto an existing data source.
- 449 -
405 Invalid request method Request type was somethingother than a GET.
Create ProjectDescription Creates a project on the specified site.
Method andURI
POST /api/2.0/sites/site-id/projects
MessagePayload
<tsRequest><project name="project-name"
description="project-description" /></tsRequest>
ResponseCode
201
ResponsePayload
<tsResponse><project id="new-project-id"
name="project-name”description="project-description" />
</tsResponse>ResponseHeaders
Location: /api/2.0/sites/site-id/projects/new-project-id
Payload Details
The project-name attribute is required for this operation; the project-descriptionattribute is optional.
Error Conditions
HTTP Response Code Condition Details404 Site not found The site ID given in the URI
does not correspond to anexisting site.
405 Invalid request method Request type was somethingother than a POST.
409 Project name conflict The project name in therequest already belongs tothe given site in the system.For the purpose ofuniqueness checks, project
- 450 -
names are case-insensitive.
Delete ProjectDescription Deletes the specified project on a specific site.
Method and URI DELETE/api/2.0/sites/site-id/projects/project-id
Message Payload NoneResponse Code 204Response Payload None
Business Logic and Error Conditions
When a project is deleted in the system all of its assets are also deleted: associated workbooks,datasources, project view options, and rights. Use thismethod with caution.Error Conditions
HTTP Response Code Condition Details403 Deletion forbidden Attempt to delete the
default project, which can-not be deleted.
404 Site not found The site ID or URLnamespace given in theURI does not correspond toan existing site.
404 Project not found Either the project ID givenin the URI does notcorrespond to an existingproject or the project is notfound on this site.
405 Invalid request method Request type wassomething other than aDELETE.
- 451 -
Update ProjectDescription Updates the name or description of the specified project.
Method and URI PUT /api/2.0/sites/site-id/projects/project-id
Message Payload <tsRequest><project name="some-new-name"
description="some-new-description" /></tsRequest>
Response Code 200Response Payload <tsResponse>
<project name="some-name"description=”some-description” />
</tsResponse>
Business Logic and Error ConditionsPayload Variations
Any combination of the attributes inside the <project> element is valid. Only those attributespresent will result in updates to their values in the project. If no attributes are present, then theupdate won't have an effect.
HTTP Response Code Condition Details403 Update forbidden Attempt to rename the
default project.404 Site not found The site ID given in the URI
does not correspond to anexisting site.
404 Project not found The project ID given in theURI does not correspond toan existing project.
404 Project ID mismatch The payload contains a pro-ject ID (which is optional)and it does not match upwith the ID in the URI.
405 Invalid request method Request type was some-thing other than a PUT.
409 Project name conflict The project name in therequest already belongs tothe given site in the system.For the purpose of unique-ness checks, project namesare case-insensitive.
- 452 -
Add Tags to WorkbookDescription Adds one or more tags to the specified workbook.
Method and URI PUT /api/2.0/sites/site-id/workbooks/workbook-id
Message Payload <tsRequest><workbook id="workbook-id">
<tags><tag label="tag1" /><tag label="tag2" />... more tags ...
</tags></workbook>
</tsRequest>Response Code 200Response Payload <tsResponse>
<workbook id="workbook-id"name="workbook-name"
><project id="project-id"
name="project-name" /><tags>
<tag label="tag1"/><tag label="tag2"/>... more tags ...
</tags><views>
<view id="view1-id" /><view id="view2-id" />... more views ...
</views></workbook>
</tsResponse>
Payload Details
If the workbook is already tagged with any tags in the payload, then those tags are ignored andthe workbook retains them. If the tags element is empty, no new tags are added to theworkbook.
- 453 -
Business Logic and Error ConditionsNon-Administrator Access
Tableau Server users who are not administrators can use thismethod but they can only add atag to workbook for which they have theAdd Tag capability allowed (either explicitly orimplicitly).
HTTP Response Code Condition Details403 Adding tags forbidden A Tableau Server user who
isn't an administratorinvoked the API methodand attempted to add a tagto a workbook for which heor she did not have theAddTag capability allowed. Thiserror is raised even in thecase when the tagselement is empty.
404 Site not found The site ID given in the URIis not for an existing site.
404 Workbook not found The workbook ID given inURI does not correspond toan existing workbook.
404 Workbook ID mismatch The payload contains aworkbook ID (which isoptional) and it does notmatch the ID in the URI.
405 Invalid request method Request type was some-thing other than a PUT.
Delete Tag fromWorkbookDescription Deletes a tag from the specified workbook.
Method and URI DELETE /api/2.0/sites/site-id/workbooks/workbook-id/tags/tag-name
Message Payload NoneResponse Code 204Response Payload None
- 454 -
Business Logic and Error ConditionsNon-Admin User Access
Tableau Server users who are not administrators can access this API method, but they canonly delete a tag from aworkbook for which they have the capability implicitly allowed (in otherwords, as owner of the workbook).
HTTP Response Code Condition Details403 Deleting tags forbidden A Tableau Server user who
isn’t an administratorinvoked the API methodand attempted to delete atag from aworkbook forwhich he or she did nothave the capability implicitlyallowed.
404 Site not found The site ID or URLnamespace given in theURI does not correspond toan existing site.
404 Workbook not found The workbook ID given inthe URI does not cor-respond to an existing work-book.
404 Tag not found The tag given in the URIdoes not exist for the givenworkbook.
405 Invalid request method Request type was some-thing other than a DELETE.
Query WorkbookDescription Returnsmetadata about the specified workbook, optionally
including a thumbnail.
Method and URI GET /api/2.0/sites/site-id/workbooks/workbook-id
GET /api/2.0/sites/site-id/workbooks/workbook-
- 455 -
id?previewImage=false
Message Payload NoneResponse Code 200Response Payload <tsResponse>
<workbook id="workbook-id"name="some-name"description="some-description" ><project id="project-id"
name="project-name" /><tags>
<tag label="tag1"/><tag label="tag2"/>... more tags ...
</tags><views>
<view id="view1-id"/><view id="view2-id"/>... more views ...
</views></workbook>
</tsResponse>
Query Workbook with a Preview Image
Description Returnsmetadata about the specified workbook, including athumbnail.
Method and URI GET /api/2.0/sites/site-id/workbooks/workbook-id?previewImage=true
Message Payload None Response Code 200Response Payload Same as above embedded in aMIMEmultipart message with
the following format:
MIME header
XML payload (in the format shown in the above table)
The binary preview image.
- 456 -
Payload Details
An example of the full response format follows. TheMIMEmultipart message is shown split byparts via a table, and the "interpart boundary" text is omitted as the table rows act to showwhere this delimiter would occur.
MIME-Version: 1.0Content-Type: multipart/mixed; boundary=interpartBoundary
Content-Type: text/xml
<tsResponse><workbook>
<!-- see markup example from previous section --></workbook>
</tsResponse>
Content-Disposition: name="myPreviewImage"; filename="foo"Content-Transfer-Encoding: binaryContent-Type: application/octet-stream
...the-tableau-workbook-preview-image-goes-here...
Business Logic and Error ConditionsNon-Administrator User Access
Tableau Server users can access this API method, but they can only query workbooks forwhich they have theRead capability allowed (either explicitly or implicitly).
HTTP Response Code Condition Details400 Invalid URI parameters The previewImage
parameter is specified but ithas a value other than trueor false.
403 Read forbidden A user who isn’t anadministrator invoked theAPI method and attemptedto query workbooks forwhich he or she does nothave theRead capabilityallowed.
404 Workbook not found The workbook ID given inthe URI does not cor-respond to an existing work-book.
- 457 -
404 Site not found The site ID given in the URIdoes not correspond to anexisting site.
405 Invalid request method Request type was some-thing other than a GET.
Add Workbook to FavoritesDescription Adds the specified workbook to a user’s favorites,
Method and URI PUT /api/2.0/sites/site-id/favorites/user-id
Message Payload <tsRequest><favorite label="favorite-label">
<workbook id="workbook-id" /></favorite>
</tsRequest>Response Code 200Response Payload <tsResponse>
<favorites><favorite label="favorite-label">
<workbook id="workbook-id" /></favorite><favorite label="favorite2">
<view id="view-id" /></favorite>... more favorites ...
</favorites></tsResponse>
If the user already has the workbook in his or her favorites with the same label, then theoperation will have no effect. If the label differs, then the original favorite is overwritten.
Business Logic and Error ConditionsNon-Administrator User Access
Tableau Server users can access this API method, but they can only add a workbook to aFavorites list if they have theAdd Favorite capability allowed for the workbook (eitherexplicitly or implicitly).
- 458 -
HTTP Response Code Condition Details400 Invalid label The favorite label is empty
or consists of only whitespace characters.
403 Access to Favorites forbidden A Tableau Server userinvoked the API methodand attempted to add aworkbook to their Favoriteslist without theAddFavorite capability. Thiswill always be the casewhen the user ID in the URIidentifies a user other thanthe user invoking themethod.
404 User not found The user ID given in theURI does not correspond toan existing user.
404 Site not found The site ID given in the URIdoes not correspond to anexisting site.
404 Workbook not found The workbook ID given inthe payload does not cor-respond to an existing work-book.
405 Invalid request method Request type was some-thing other than a PUT.
409 Label conflict There is already a favoritewith the same label for a dif-ferent workbook in thegiven user's favorites.
Delete Workbook from FavoritesDescription Deletes a workbook from a user’s favorites.
Method and URI DELETE/api/2.0/sites/site-id/favorites/user-id/workbooks/workbook-id
- 459 -
Message Payload NoneResponse Code 204Response Payload None
Business Logic and Error Conditions
If the workbook you specify isn't a Favorite, then this call has no effect.Non-Administrator User Access
Tableau Server users can access this API method, but they can only delete a workbook fromtheir own Favorites list.Error Conditions
HTTP Response Code Condition Details403 Access to Favorites forbidden A Tableau Server user
invoked the API methodand attempted to delete aworkbook from a differentuser's favorites..
404 User not found The user ID given in theURI does not correspond toan existing user.
404 Site not found The site ID given in the URIdoes not correspond to anexisting site.
404 Workbook not found The workbook ID given inthe payload does not cor-respond to an existing work-book.
404 Workbook not a favorite The workbook ID given inthe URI exists but is not afavorite of the given user.
405 Invalid request method Request type was some-thing other than aDELETE.
Query View with a Preview ImageDescription Return the thumbnail for a specific view.
Method and URI GET /api/2.0/sites/site-
- 460 -
id/workbooks/workbook-id/views/view-id/previewImage
Message Payload NoneResponse Code 200Response Payload The view's preview image in PNG format (MIMEmedia type
image/png).
Business Logic and Error ConditionsNon-Administrator User Access
Tableau Server users can can access this API method, but they can only query workbookviews for which they have theRead capability allowed (either explicitly or implicitly).Error Conditions
HTTP Response Code Condition Details403 Read forbidden A Tableau Server user
invoked the API methodand attempted to query aworkbook view for which heor she did not have theRead capability allowed.
404 View not found The view ID given in theURI does not correspond toan existing view in the givenworkbook.
404 Site not found The site ID given in the URIdoes not correspond to anexisting site.
404 Workbook not found The workbook ID given inthe payload does not cor-respond to an existing work-book.
405 Invalid request method Request type was some-thing other than aDELETE.
Query Views for WorkbookDescription Return all the views for the specified workbook, optionally
including usage statistics.
- 461 -
Method and URI GET /api/2.0/sites/site-id/workbooks/workbook-id/views
GET /api/2.0/sites/site-id/workbooks/workbook-id/views?includeUsageStatistics=false
Message Payload NoneResponse Code 200Response Payload <tsResponse>
<views><view id="view1-id" name="view1-name" /><view id="view2-id" name="view2-name" />... more views ...
</views></tsResponse>
Query Views with Usage Statistics
Method and URI GET /api/2.0/sites/site-id/workbooks/workbook-id/views?includeUsageStatistics=true
Message Payload NoneResponse Code 200Response Payload <tsResponse>
<views><view id="view1-id" name="view1-name" >
<usage totalViewCount="total-count1" /></view><view id="view2-id" name="view2-name" >
<usage totalViewCount="total-count2" /></view>... more views ...
</views></tsResponse>
Business Logic and Error ConditionsNon-Administrator User Access
Tableau Server users can access this API method, but they can only query workbook views forwhich they have theRead capability allowed (either explicitly or implicitly).
- 462 -
Error Conditions
HTTP Response Code Condition Details400 Invalid parameter value The includeUsageS-
tatistics was provided witha value other than true orfalse
403 Read forbidden A Tableau Server user invokedthe API method and attemptedto query workbook views forwhich he or she did not havethe Read capability allowed.
404 Site not found The site ID given in the URIdoes not correspond to an exist-ing site.
404 Workbook not found The workbook ID given in thepayload does not correspond toan existing workbook.
405 Invalid request method Request type was somethingother than aGET.
Query Workbook Preview ImageDescription Returns the thumbnail for a specified workbook. Usually the
image that's returned is for the first sheet in the workbook.
Method and URI GET /api/2.0/sites/site-id/workbooks/workbook-id/previewImage
Message Payload NoneResponse Code 200Response Payload Theworkbook's preview image in PNG format (MIMEmedia
type image/png).
Business Logic and Error Conditions
For on-premise Tableau Server deployments and for Tableau Public, the system returns thepreview image associated with the lowest index view in the workbook.Non-Administrator User Access
Tableau Server users can use this API method, but they can only fetch preview images forworkbooks for which they have theRead capability allowed (either explicitly or implicitly).
- 463 -
Error Conditions
HTTP Response Code Condition Details403 Read forbidden A Tableau Server user
invoked the API methodand attempted to queryworkbook views for whichhe or she did not have theRead capability allowed.
404 Site not found The site ID given in the URIdoes not correspond to anexisting site.
404 Workbook not found The workbook ID given inthe payload does not cor-respond to an existing work-book.
405 Invalid request method Request type was some-thing other than aGET.
Query Workbooks for UserDescri-ption
Return the workbooks associated with a specific user, optionally including pagingparameters.
Metho-d andURI
GET /api/2.0/sites/site-id/users/user-id/workbooks
GET /api/2.0/sites/site-id/users/user-id/workbooks?pageSize=page-size&pageNumber=page-number
Mes-sagePay-load
None
Respo-nseCode
200
Respo-nsePay-load
<tsResponse><pagination pageNumber="pageNumber" pageSize="page-size"
totalAvailable="total-available" /><workbooks>
- 464 -
<workbook id="workbook1-id"name=”some-name” ><project id="project-id" name="project-name" />
<tags><tag label="tag1"/><tag label="tag2"/>... more tags ...
</tags><views>
<view id="view1-id"/><view id="view2-id"/>... more views ...
</views></workbook><workbook id="workbook2-id"
name="some-name" ><project id="project-id" name="project-name" />
<tags><tag label="tag1"/><tag label="tag2"/>... more tags ...
</tags><views>
<view id="view1-id"/><view id="view2-id"/>... more views ...
</views></workbook></workbooks>
... more workbooks ...</tsResponse>
Business Logic and Error ConditionsNon-Administrator User Access
Tableau Server users can use this API method, but they can only query workbooks for whichthey have theRead capability allowed (either explicitly or implicitly).Pagination Parameter Defaults
By default the page size is 100 and page 1 is served. One or both parameters can beoverridden explicitly.Error Conditions
HTTP Response Code Condition Details403 Read forbidden A Tableau Server user
invoked the API method
- 465 -
and attempted to queryworkbook views for whichhe or she did not have theRead capability allowed.
404 Site not found The site ID given in the URIdoes not correspond to anexisting site.
404 User not found The user ID given in theURI does not correspond toan existing user.
405 Invalid request method Request type was some-thing other than aGET.
Add User to SiteDescription Adds a user to the specified site.
Method and URI POST /api/2.0/sites/site-id/users/
Message Payload <tsRequest><user name="user-name"
role="some-role"publish="true-or-false"contentAdmin="true-or-false*"suppressGettingStarted="true-or-false" />
</tsRequest>Response Code 201Response Payload <tsResponse>
<user id="user-id"name="user-name"role="some-role"publish="true-or-false"contentAdmin="true-or-false"suppressGettingStarted="true-or-false" />
</tsResponse>Response Headers Location: /api/2.0/sites/site-id/users/new-user-id
Payload Details
There are three valid roles available: Interactor, Viewer, and Unlicensed.
- 466 -
The contentAdmin parameter can only be true if the role is Interactor. For any other role, avalue of contentAdmin in the request payload will be ignored, and the value false will beused and subsequently returned in the response payload.
The suppressGettingStarted parameter may be omitted. If it is, the user will retain theirexisting preference if he or she is already amember of another site. If the user is new to thesystem, the preference will be set to the default according to user type: enabled for siteadministrators, suppressed for others.Error Conditions
HTTP Response Code Condition Details404 Site not found The site ID given in the URI
does not correspond to anexisting site.
404 User name not found The user name given in thepayload does not cor-respond to an existing userin the system.
405 Invalid request method Request type was some-thing other than a POST or aGET.
409 User conflict The given user is alreadyregistered on the site.
409 Guest user conflict The TableauOnline API dis-allows adding a user withthe guest role to a site.
Get Users on SiteDescrip-tion
Returns the users associated with the specified site.
Methodand URI
GET /api/2.0/sites/site-id/users/
MessagePayload
None
Respons-e Code
200
Respons-e Pay-load
<tsResponse><users>
- 467 -
<user id="user1-id"name="user1-name"role="some-role"publish="true-or-false"contentAdmin="true-or-false"lastLogin="YYYY-MM-DDTHH:MM:SSZ"externalAuthUserId="authentication-id-from-external-
provider"/><user id="user2-id"
name="user2-name"role="some-role"publish="true-or-false"contentAdmin="true-or-false"
lastLogin="YYYY-MM-DDTHH:MM:SSZ"externalAuthUserId="authentication-id-from-external-
provider" />...</users>
</tsResponse>
Error Conditions
HTTP Response Code Condition Details404 Site not found The site ID given in the URI
does not correspond to anexisting site.
405 Invalid request method Request type was some-thing other than a POST or aGET.
Remove User from SiteDescription Removes a user from the specified site.
Method and URI DELETE /api/2.0/sites/site-id/users/user-id
Message Payload NoneResponse Code 204Response Payload None
- 468 -
Business Logic and Error Conditions
If a user still owns content on Tableau Server, the user cannot be deleted. The ownership ofthe user’s content will need tomove to a different user first.Error Conditions
HTTP Response Code Condition Details400 Deletion failed Some other problem arose
that prevented the userfrom being removed fromthe site.
404 Site not found The site ID given in the URIdoes not correspond to anexisting site.
404 User not found The user ID given in theURI does not correspond toan existing user.
405 Invalid request method Request type was some-thing other than a DELETE,a POST, or a GET.
409 User asset conflict The given user still ownscontent on Tableau Server.
Create SiteDescription Creates a site on Tableau Server with the givenmetadata.
Method and URI POST /api/2.0/sites/
Message Payload <tsRequest><site name="site-name"
contentUrl="some-content-url"adminMode="some-admin-mode"userQuota="num-users"storageQuota="limit-in-megabytes"
disableSubscriptions="false" /></tsRequest>
Response Code 201Response Payload <tsResponse>
<site id="new-site-id"name="site-name"
- 469 -
contentUrl="the-content-url"adminMode="the-admin-mode"userQuota="num-users"storageQuota="limit-in-megabytes"
disableSubscriptions="false" /></tsResponse>
Response Headers Location: /api/2.0/sites/new-site-id
Payload Details
There are two valid adminmodes: ContentOnly and ContentAndUsers. Note thatadminMode, userQuota and storageQuota are optional parameters.
Business Logic and Error Conditions
You cannot set adminMode to ContentOnly and also set a userQuota.Error Conditions
HTTP Response Code Condition Details405 Invalid request method Request type was some-
thing other than a POST or aGET.
409 Site name conflict The site name in therequest already belongs toan existing site in the sys-tem.
409 Site URL conflict The content URL in therequest already belongs toan existing site in the sys-tem.
409 Adminmode/user quota conflict The request cannot setadminMode to ContentOnlyand specify a userQuota.
Update SiteDescription Modifies themetadata of the specified site.
Method and URI PUT /api/2.0/sites/site-id
Message Payload <tsResponse>
- 470 -
<site name="some-name"contentUrl="some-content-url"adminMode="some-admin-mode"userQuota="num-users"
state="active-or-suspended"statusReason="reason-for-state"
storageQuota="limit-in-megabytes"disableSubscriptions="true-or-false" />
</tsResponse>Response Code 200Response Payload <tsResponse>
<site name="some-name"contentUrl="some-content-url"adminMode="some-admin-mode"userQuota="num-users"
state="active-or-suspended"statusReason="reason-for-state"
storageQuota="limit-in-megabytes"disableSubscriptions="true-or-false" />
</tsResponse>
Payload Details
There are two valid adminmodes: ContentOnly and ContentAndUsers.
Setting userQuota to -1 removes any value that was set previously. In that case, the limit onusers depends on the type of licensing configured for the server. For user-based licensing, themaximumnumber of users is set by the license. For core-based licensing, there is no limit to thenumber of users.
Business Logic and Error ConditionsPayload Variations
Any combination of the attributes inside the <site> element is valid. Only those attributespresent will result in updates to their values in the site. If no attributes are present, then theupdate will not take effect.Error Conditions
HTTP Response Code Condition Details400 Invalid adminmode An adminmode parameter
was provided in the requestwith an invalid value.
400 Invalid state A state parameter wasprovided in the request withan invalid value
404 Site not found The site ID given in the URI
- 471 -
does not correspond to anexisting site.
404 User name not found The user name given in thepayload does not cor-respond to an existing userin the system.
405 Invalid request method Request type was some-thing other than a PUT, aDELETE, or a GET.
409 Site name conflict The new site name in therequest already belongs toan existing site in the sys-tem.
409 Site URL conflict The new content URL in therequest already belongs toan existing site in the sys-tem.
Query SitesDescr-iption
Returns a list of all sites on the server.
Metho-d andURI
GET/api/2.0/sites/
GET/api/2.0/sites/?includeProjects=false
Mes-sagePay-load
None
Resp-onseCode
200
Resp-onsePay-load
<tsResponse><sites><site id="site-id"name="site1-name"
- 472 -
contentUrl="site1-content-url"adminMode="some-admin-mode"userQuota="num-users"
storageQuota="limit-in-megabytes"state="active-or-suspended"statusReason="reason-for-state" /><projects><project id="project1-id" name="project1-name"/><project id="project2-id" name="project2-name"/>... more projects ...
</projects></site><site id="site2-id"name="site2-name"contentUrl="site2-content-url"adminMode="some-admin-mode"userQuota="num-users"
storageQuota="limit-in-megabytes"state="active-or-suspended"statusReason="reason-for-state" /><projects><project id="project3-id" name="project3-name"/><project id="project4-id" name="project4-name"/>... more projects ...
</projects></site>
</sites></tsResponse>
Error Conditions
HTTP Response Code Condition Details405 Invalid request method Request type was some-
thing other than a POST orGET.
Query SiteDescr-iption
Returnsmetadata on the specified site, which can be queried by name, site-id, or thesite URL.
Metho-d andURI
Query by Site ID GET/api/2.0/sites/site-id
- 473 -
Query by Site NameGET/api/2.0/sites/site-name?key=name
Query byURLNamespaceGET/api/2.0/sites/site-url-namespace?key=contentUrl
Mes-sagePay-load
None
Resp-onseCode
200
Resp-onsePay-load
<tsResponse><site id="site-id"name="some-name"
contentUrl="some-content-url"adminMode="some-admin-mode"userQuota="num-users"
storageQuota="limit-in-megabytes"state="active-or-suspended"statusReason="reason-for-state" />
</tsResponse>
Site Information Including Storage Usage
Meth-odandURI
Query by Site IDGET/api/2.0/sites/site-id?includeUsage=true
Query byNameGET/api/2.0/sites/site-name?key=name&includeUsage=true
Query byURLNamespaceGET/api/2.0/sites/site-url-namespace?key=contentUrl&includeUsage=true
Mes-sagePay-load
None
- 474 -
Resp-onseCode
200
Resp-onsePay-load
<tsResponse><site id="site-id"name="some-name"
contentUrl="some-content-url"adminMode="some-admin-mode"userQuota="num-users"
storageQuota="limit-in-megabytes"state="active-or-suspended"
statusReason="reason-for-state" ><usage numUsers="the-number-of-users"
storage="the-storage-in-megabytes"</usage></site>
</tsResponse>
Error Conditions
HTTP Response Code Condition Details404 Site not found The site ID or URL
namespace given in theURI does not correspond toan existing site.
405 Invalid request method Request type was some-thing other than a GET,DELETE, or PUT.
Delete SiteDescr-iption
Deletes the specified site.
Metho-d andURI
Delete by Site ID DELETE/api/2.0/sites/site-id
Delete by Site NameDELETE/api/2.0/sites/site-name?key=name
Delete byURLNamespace DELETE/api/2.0/sites/site-url-
- 475 -
namespace?key=contentUrl
Mes-sagePay-load
None
Resp-onseCode
204
Resp-onsePay-load
None
Error Conditions
HTTP Response Code Condition Details403 Deletion forbidden Attempt to delete the
default Tableau Server site.404 Site not found The site ID or URL
namespace given in theURI does not correspond toan existing site.
405 Invalid request method Request type was some-thing other than a GET,DELETE, or PUT.
- 476 -
Contact UsDirectory of worldwide offices
SalesContact
Support1. Search our support resources.
2. Review the search results to see if your question is answered.
3. If you can't find what you need, scroll to the bottom of the search results, and clickContinue and Create Case.
- 477 -
Copyright©2015 Tableau Software, Incorporated and its licensors. All rights reserved.
Patent www.tableausoftware.com/ip.
Portions of the code copyright ©2002 The Board of Trustees of the Leland Stanford JuniorUniversity. All rights reserved.
Tableau’s installation includes an unmodified executable version of the Firebird database. Thesource code for that database can be found at http://www.firebirdsql.org
For a listing of third party copyright notices please refer to the following file that is installed withTableau Server:
C:\Program Files\Tableau\Tableau Server\8.2\COPYRIGHTS.rtf
Note: If you installed 32-bit Tableau Server on a 64-bit operating system, it will be inC:\Program Files (x86)\Tableau\TableauServer\8.2\COPYRIGHTS.rtf
This product includes software developed by AndyClark.
This product includes software developed by the Apache Software Foundation(http://www.apache.org/).
This product is Client Software as defined in Tableau Software’s End User Software LicenseAgreement.
