From f7a5717c1a350221dd8c6b3f772e217b2c7e7fe9 Mon Sep 17 00:00:00 2001 From: Jac Fitzgerald Date: Mon, 9 Nov 2026 13:51:04 -0800 Subject: [PATCH 1/3] Document that publish server_address matches connections rather than changing them Users passing a ConnectionItem with a new server_address to workbooks.publish expected the published connection to point at that server, and got error 403007 instead. The server uses server_address to find the matching connection embedded in the workbook file; it does not change it. Explain this, show how to change the address afterwards with workbooks.update_connection, and correct the ConnectionItem server_address description (it is the data source host, not the Tableau Server host). Closes #337 Co-Authored-By: Claude Code --- docs/api-ref.md | 25 +++++++++++++++++++++++-- 1 file changed, 23 insertions(+), 2 deletions(-) diff --git a/docs/api-ref.md b/docs/api-ref.md index 104213764..7fe2a18ea 100644 --- a/docs/api-ref.md +++ b/docs/api-ref.md @@ -679,7 +679,7 @@ Name | Description `username` | The username for the connection (see ConnectionCredentials). `password` | The password used for the connection (see ConnectionCredentials). `embed_password` | (Boolean) Determines whether to embed the password (`True`) for the workbook or data source connection or not (`False`) (see ConnectionCredentials). -`server_address` | The server address for the connection (host name for the Tableau Server). +`server_address` | The server address for the connection (host name of the data source server). When publishing a workbook, this identifies which embedded connection the credentials apply to and does not change it; use `workbooks.update_connection` to change it after publishing. `server_port` | The port used for the connection. `connection_credentials` | The Connection Credentials object containing authentication details for the connection. Replaces username/password/embed_password when publishing a flow, document or workbook file in the request body. `workgroup_auth_mode` | (Optional) The Workload Identity Federation (WIF) auth mode for the connection. Set to one of the values on the `ConnectionItem.WorkgroupAuthMode` nested value set: `WIF` (`"workload-identity-federation"`, e.g. Snowflake direct WIF) or `WIF_IMPERSONATION` (`"workload-identity-federation-impersonation"`, e.g. Google BigQuery impersonation WIF). Requires REST API 3.30+ (Tableau Server release 26.3) with WIF configured on the site. Older servers silently ignore the attribute. @@ -10407,10 +10407,12 @@ Name | Description `workbook_item` | The `workbook_item` specifies the workbook you are publishing. When you are adding a workbook, you need to first create a new instance of a `workbook_item` that includes a `project_id` of an existing project. The name of the workbook will be the name of the file, unless you also specify a name for the new workbook when you create the instance. See [WorkbookItem](#workbookitem-class). `file` | The file path or file object of the workbook to publish. When providing a file object, you must also specifiy the name of the workbook in your instance of the `workbook_item``workbook_item` , as the name cannot be derived from the file name. `mode` | Specifies whether you are publishing a new workbook (`CreateNew`) or overwriting an existing workbook (`Overwrite`). You cannot appending workbooks. You can also use the publish mode attributes, for example: `TSC.Server.PublishMode.Overwrite`. -`connections` | List of `ConnectionItems` objects for the connections created within the workbook. +`connections` | List of `ConnectionItems` objects that supply credentials for the connections embedded in the workbook. The `server_address` of each item is used to find the matching connection in the workbook file; it does not change the connection's server address. See the note below. `skip_connection_check` | (Optional) Set to `True` to skip connection check at time of upload. Publishing will succeed but unchecked connection issues may result in a non-functioning workbook. Defaults to `False`. `as_job` | (Optional) Set to `True` to run the upload as a job (asynchronous upload). If set to `True` a job will start to perform the publishing process and a `Job` object is returned. Defaults to `False`. +**Note:** When you publish, the `server_address` of each `ConnectionItem` in `connections` identifies which connection embedded in the workbook file the credentials belong to. It does not change the server address of that connection; the workbook is published with the server address saved in the file. If `server_address` does not match a connection in the file, the credentials are not applied and the publish typically fails with error `403007` (`failed to establish a connection to your datasource`). To point an embedded connection at a different server, publish the workbook first and then call [workbooks.update_connection](#workbooksupdate_connection). See the second example below. + **Exceptions** @@ -10446,6 +10448,25 @@ with server.auth.sign_in(tableau_auth): wb_item = server.workbooks.publish(wb_item, 'SampleWB.twbx', 'Overwrite') ``` +**Example: publish, then change the server address of an embedded connection** + +```py +with server.auth.sign_in(tableau_auth): + wb_item = TSC.WorkbookItem(name='Sample', project_id='1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e') + + # server_address must match the server address saved in the workbook file + connection = TSC.ConnectionItem() + connection.server_address = 'dev-db.example.com' + connection.connection_credentials = TSC.ConnectionCredentials('db_user', 'db_password', embed=True) + wb_item = server.workbooks.publish(wb_item, 'SampleWB.twbx', 'CreateNew', connections=[connection]) + + # point the published connection at a different server + server.workbooks.populate_connections(wb_item) + conn = next(c for c in wb_item.connections if c.server_address == 'dev-db.example.com') + conn.server_address = 'prod-db.example.com' + server.workbooks.update_connection(wb_item, conn) +``` +

From 79d3b53adb595e5f59f05f6109839704ba246aab Mon Sep 17 00:00:00 2001 From: Jac Fitzgerald Date: Mon, 9 Nov 2026 13:53:38 -0800 Subject: [PATCH 2/3] Correct workbooks.publish and update_connection reference entries The publish signature listed file_path and publish_mode (the parameters are file and mode) and omitted the parameters argument and defaults, a parameter description repeated workbook_item twice, and workbooks.update_connection was documented as returning None when it returns the updated ConnectionItem. Co-Authored-By: Claude Code --- docs/api-ref.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/api-ref.md b/docs/api-ref.md index 7fe2a18ea..df428630e 100644 --- a/docs/api-ref.md +++ b/docs/api-ref.md @@ -10384,7 +10384,7 @@ print(workbook.name) #### workbooks.publish ```py -workbooks.publish(workbook_item, file_path, publish_mode, connections, skip_connection_check, as_job) +workbooks.publish(workbook_item, file, mode, connections=None, as_job=False, skip_connection_check=False, parameters=None) ``` Publish a workbook to the specified site. @@ -10405,7 +10405,7 @@ REST API: [Publish Workbook](https://help.tableau.com/current/api/rest_api/en-us Name | Description :--- | :--- `workbook_item` | The `workbook_item` specifies the workbook you are publishing. When you are adding a workbook, you need to first create a new instance of a `workbook_item` that includes a `project_id` of an existing project. The name of the workbook will be the name of the file, unless you also specify a name for the new workbook when you create the instance. See [WorkbookItem](#workbookitem-class). -`file` | The file path or file object of the workbook to publish. When providing a file object, you must also specifiy the name of the workbook in your instance of the `workbook_item``workbook_item` , as the name cannot be derived from the file name. +`file` | The file path or file object of the workbook to publish. When providing a file object, you must also specifiy the name of the workbook in your instance of the `workbook_item`, as the name cannot be derived from the file name. `mode` | Specifies whether you are publishing a new workbook (`CreateNew`) or overwriting an existing workbook (`Overwrite`). You cannot appending workbooks. You can also use the publish mode attributes, for example: `TSC.Server.PublishMode.Overwrite`. `connections` | List of `ConnectionItems` objects that supply credentials for the connections embedded in the workbook. The `server_address` of each item is used to find the matching connection in the workbook file; it does not change the connection's server address. See the note below. `skip_connection_check` | (Optional) Set to `True` to skip connection check at time of upload. Publishing will succeed but unchecked connection issues may result in a non-functioning workbook. Defaults to `False`. @@ -10872,7 +10872,7 @@ Name | Description **Returns** -None. The connection information is updated with the information in the `ConnectionItem`. +The updated `ConnectionItem`. The connection information on the server is updated with the information in the `ConnectionItem` you passed in. From 08ebc10cd1b39cac2dd4fae9aa73f29f7241b8ad Mon Sep 17 00:00:00 2001 From: Jac Fitzgerald Date: Tue, 10 Nov 2026 12:50:22 -0800 Subject: [PATCH 3/3] Remove the unverified 403007 claim from the workbooks.publish note Co-Authored-By: Claude Code --- docs/api-ref.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api-ref.md b/docs/api-ref.md index df428630e..83a99ad63 100644 --- a/docs/api-ref.md +++ b/docs/api-ref.md @@ -10411,7 +10411,7 @@ Name | Description `skip_connection_check` | (Optional) Set to `True` to skip connection check at time of upload. Publishing will succeed but unchecked connection issues may result in a non-functioning workbook. Defaults to `False`. `as_job` | (Optional) Set to `True` to run the upload as a job (asynchronous upload). If set to `True` a job will start to perform the publishing process and a `Job` object is returned. Defaults to `False`. -**Note:** When you publish, the `server_address` of each `ConnectionItem` in `connections` identifies which connection embedded in the workbook file the credentials belong to. It does not change the server address of that connection; the workbook is published with the server address saved in the file. If `server_address` does not match a connection in the file, the credentials are not applied and the publish typically fails with error `403007` (`failed to establish a connection to your datasource`). To point an embedded connection at a different server, publish the workbook first and then call [workbooks.update_connection](#workbooksupdate_connection). See the second example below. +**Note:** When you publish, the `server_address` of each `ConnectionItem` in `connections` identifies which connection embedded in the workbook file the credentials belong to. It does not change the server address of that connection; the workbook is published with the server address saved in the file. If `server_address` does not match a connection in the file, the credentials are not applied. To point an embedded connection at a different server, publish the workbook first and then call [workbooks.update_connection](#workbooksupdate_connection). See the second example below.