'` before the `auth.signin` call.
+```py
+server.auth.sign_out()
+```
-The TSC library signs you out of Tableau Server when you exit out of the `with` block.
+## Simplify by using Python with block
-
- **Note:** When you sign in, the TSC library manages the authenticated session for you, however the validity of the underlying
- credentials token is limited by the maximum session length set on your Tableau Server (2 hours by default).
-
+The sign in/out flow can be simplified (and handled in a more Python way) by using the built-in support for the `with` block. After the block execution completes, the sign out is called automatically.
-An alternative to using a `with` block is to call the `Auth.sign_in` and `Auth.sign_out` functions explicitly:
+For example:
```py
import tableauserverclient as TSC
-tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD') # with no site name, this will use the Default site
-server = TSC.Server('http://SERVER_URL')
+tableau_auth = TSC.PersonalAccessTokenAuth('TOKEN_NAME', 'TOKEN_VALUE', 'SITENAME')
+server = TSC.Server('https://SERVER_URL')
+
+with server.auth.sign_in(tableau_auth):
+ all_wb, pagination_item = server.workbooks.get()
+ print("\nThere are {} workbooks on site: ".format(pagination_item.total_available))
+ for wb in all_wb:
+ print(wb.id, wb.name)
+```
-server.auth.sign_in(tableau_auth)
+All of the samples provided in TSC library use this technique.
-# Do awesome things here!
+## Switch Site
-server.auth.sign_out()
+Tableau Server has a feature which enables switching to another site without having to authenticate again. (The user must have access permissions for the new site as well.)
+
+**Note:** This method is not available on Tableau Online.
+
+The following example will switch the authenticated user to the NEW_SITENAME site on the same server:
+
+```py
+# assume we already have an authenticated server object
+
+server.auth.switch_site('NEW_SITENAME')
```
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
new file mode 100644
index 000000000..16ae51a11
--- /dev/null
+++ b/docs/troubleshooting.md
@@ -0,0 +1,54 @@
+---
+title: Troubleshooting
+layout: docs
+---
+
+This page covers some common troubleshooting tips for using the TSC library.
+
+
+ Warning: Do not post any debug logs or REST API request/response contents anywhere on GitHub. The contents may include sensitive data or authentication secrets. Instead you can post just edited snippets of relevant content after sanitizing (removing any sensitive values).
+
+
+* TOC
+{:toc}
+
+## Logging REST API communication with Tableau Server
+
+There may be cases where it's helpful to inspect the REST API calls the TSC library is making and the responses coming back from Tableau Server. Some examples might be:
+
+* The TSC library is throwing an error or the results are not coming through as expected
+* The TSC library or the REST backend may have a bug which needs to be tracked down
+
+To enable logging, add the following to your Python script ahead of making any TSC calls:
+
+```py
+import logging
+logging.basicConfig(format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
+ filename="tsc.log", level="DEBUG")
+```
+
+Now when your script executes, you'll see a set of debug messages in the `tsc.log` file. Each API call to the REST API will be included along with the XML responses. Depending on the problem being investigated, you can compare these requests/responses to the [REST API documentation](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api.htm) to track down the issue.
+
+## Capture REST API communication with local proxy
+
+Another approach for inspecting REST API traffic is to use a local debugging proxy server like [Fiddler Everywhere](https://www.telerik.com/fiddler). Fiddler Everywhere is free for basic use and has versions for Mac, Windows and Linux.
+
+These are the steps to send the API traffic through to a local proxy like Fiddler:
+
+1. Install Fiddler Everywhere and create a free account if needed
+2. Launch the Fiddler app and click the settings (gear) icon to enable Capture HTTPS traffic. (Do not click Trust root certificate.)
+3. Before running your script, set the following environment variables (on Windows, use SET commands instead):
+```shell
+export HTTP_PROXY=127.0.0.1:8866
+export HTTPS_PROXY=127.0.0.1:8866
+export CURL_CA_BUNDLE=""
+export PYTHONWARNINGS="ignore:Unverified HTTPS request"
+```
+4. Run your script
+5. Check Fiddler Everywhere for the results
+
+The sample screenshot below shows the results of running a simple sign in/out sequence. The Capture pane includes one row for each HTTP request. Select the request to see the details on the right side: Request and Response.
+
+
+
+Proxy server applications other than Fiddler can be used as well. Just adjust the HTTP_PROXY and HTTPS_PROXY environment variables to use the proper IP address and port number.
diff --git a/docs/versions.md b/docs/versions.md
index 70076aa6e..b8f824f6e 100644
--- a/docs/versions.md
+++ b/docs/versions.md
@@ -6,6 +6,8 @@ layout: docs
Because the TSC library is a client for the Tableau Server REST API, you need to confirm that the version of the TSC
library that you use is compatible with the version of the REST API used by your installation of Tableau Server.
+For reference, the [REST API and Resource Versions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm) page has more details about versions.
+
* TOC
{:toc}
@@ -21,11 +23,11 @@ server = TSC.Server('http://SERVER_URL')
print(server.version)
```
-For example, the code might display version `2.3`.
+For example, the code might display version `2.3`.
## Use the REST API version supported by the server
-There are two options for always using the the latest version of the REST API that is supported by the instance of Tableau Server you are connecting to.
+There are two options for always using the the latest version of the REST API that is supported by the instance of Tableau Server you are connecting to. This could be necessary in cases where you're using an API feature that is only supported in a newer REST API version.
The first method is to specify `use_server_version=True` as one of the arguments, for example:
@@ -52,7 +54,7 @@ To use a specific version of the REST API, set the version like so:
import tableauserverclient as TSC
server = TSC.Server('http://SERVER_URL')
-server.version = '2.6'
+server.version = '3.6'
```
@@ -62,6 +64,7 @@ The current version of TSC only supports the following REST API and Tableau Serv
|REST API version|Tableau Server version|
|---|---|
+|3.9|2020.3|
|3.8|2020.2|
|3.7|2020.1|
|3.6|2019.4|