--- schema_version: "1" id: 872c4d0a05e2e90bcccd1419ba444f35d707f3e0d0d7e4f22348658971fa23ad title: TSM API Reference collection: tableau version: next locale: en-us portal_url: https://docs.salesforce.com/tableau/next/en-us/api/tsm_api/docs/tsm-reference.md canonical_url: https://help.tableau.com/v0.0/api/tsm_api/en-us/docs/tsm-reference.htm source_site: help.tableau.com content_type: documentation content_hash: 9a80efe949de78d5c3c0f2f61d746d5fe01941d4796e6af9ca54e43f046f3e58 description: Documentation for Tableau Services Manager API --- # TSM API Reference This page describes the Tableau Services Manager (TSM) API endpoints (or methods), organized by category. For more information about how to make requests and for information about request parameters, see [Get started](/v0.0/api/tsm_api/en-us/index.htm). * * * ## Async jobs Get information about asynchronous jobs. ### List async jobs Get a list of TSM jobs, and for each job display information about the status, progress, ID, job type, and more. ``` GET /asyncJobs ``` #### Request query parameters `status` Optional. Only return jobs that match the provided status. Valid statuses include **Succeeded**, **Failed**, **Created**, and **Running**. #### Response status code 200 OK #### Response body example ``` { "asyncJobs": [{ "progress": 100, "id": 4, "status": "Succeeded", "detailedProgress": { "progressNotes": [{ "step": "DisableAllServices", "messageData": [], "message": "Disabling all services.", "timestamp": 1497041247968, "status": "Running" }, { "step": "DisableAllServices", "messageData": [], "message": "Disabling all services.", "timestamp": 1497041248035, "status": "Succeeded" }, { "step": "StopAllServices", "messageData": [], "message": "Waiting for the services to stop.", "timestamp": 1497041248040, "status": "Running" }, { "step": "StopAllServices", "messageData": [], "message": "Waiting for the services to stop.", "timestamp": 1497041432154, "status": "Succeeded" }], "doneSteps": 2, "totalSteps": 2 }, "jobType": "StopServerJob", "createdAt": 1497041247933, "updatedAt": 1497041432165, "statusMessageData": [], "jobTimeout": 300, "worker": "node1", "completedAt": 1497041432165, "statusMessage": "This job completed successfully." }, { "..." }] } ``` ### Get async job by job ID Get the state of a previously started job. ``` GET /asyncJobs/ ``` #### Request path parameters `jobId` The ID of the asychronous job. To view a list of jobs and job IDs, see [List async jobs](#list-async-jobs). #### Response status code 200 OK #### Response body example ``` { "asyncJob": { "progress": 100, "id": 4, "status": "Succeeded", "detailedProgress": { "progressNotes": [ { "step": "DisableAllServices", "messageData": [], "message": "Disabling all services.", "timestamp": 1497041247968, "status": "Running" }, { "step": "DisableAllServices", "messageData": [], "message": "Disabling all services.", "timestamp": 1497041248035, "status": "Succeeded" }, { "step": "StopAllServices", "messageData": [], "message": "Waiting for the services to stop.", "timestamp": 1497041248040, "status": "Running" }, { "step": "StopAllServices", "messageData": [], "message": "Waiting for the services to stop.", "timestamp": 1497041432154, "status": "Succeeded" } ], "doneSteps": 2, "totalSteps": 2 }, "jobType": "StopServerJob", "createdAt": 1497041247933, "updatedAt": 1497041432165, "statusMessageData": [], "jobTimeout": 300, "worker": "node1", "completedAt": 1497041432165, "statusMessage": "This job completed successfully." } } ``` ### Get latest async job Get the status of the latest added asynchronous job, across all job types. ``` GET /asyncJobs/latest ``` #### Response status code 200 OK #### Response body example ``` { "asyncJob": { "progress": 100, "id": 23, "status": "Succeeded", "detailedProgress": { "progressNotes": [ { "step": "ConfigureServices", "messageData": [], "message": "Reconfiguring services.", "timestamp": 1505842758105, "status": "Running" }, { "step": "ConfigureServices", "messageData": [], "message": "Reconfiguring services.", "timestamp": 1505842758126, "status": "Succeeded" }, { "step": "WaitForConfigureAndStart", "messageData": [], "message": "Waiting for services to reconfigure and start.", "timestamp": 1505842758137, "status": "Running" }, { "step": "WaitForConfigureAndStart", "messageData": [], "message": "Waiting for services to reconfigure and start.", "timestamp": 1505843134048, "status": "Succeeded" } ], "doneSteps": 2, "totalSteps": 2 }, "jobType": "ReconfigureJob", "createdAt": 1505842758085, "updatedAt": 1505843134060, "statusMessageData": [], "jobTimeout": 420, "worker": "node1", "completedAt": 1505843134060, "statusMessage": "This job completed successfully." } } ``` ### Get latest async job by type Get the state of the last async job that started that matches the specified job type. See ``` /asyncJobs/latest/ ``` #### Request path parameters `jobType` Required. The type of job. To view a list of available job types, see [List async jobs](#list-async-jobs). #### Response status code 200 OK #### Response body example ``` { "asyncJob": { "progress": 100, "id": 19, "status": "Succeeded", "detailedProgress": { "progressNotes": [ { "step": "DisableAllServices", "messageData": [], "message": "Disabling all services.", "timestamp": 1505245656514, "status": "Running" }, { "step": "DisableAllServices", "messageData": [], "message": "Disabling all services.", "timestamp": 1505245658760, "status": "Succeeded" }, { "step": "StopAllServices", "messageData": [], "message": "Waiting for the services to stop.", "timestamp": 1505245658764, "status": "Running" }, { "step": "StopAllServices", "messageData": [], "message": "Waiting for the services to stop.", "timestamp": 1505245691691, "status": "Succeeded" }, { "step": "EnableAllServices", "messageData": [], "message": "Enabling all services.", "timestamp": 1505245691698, "status": "Running" }, { "step": "EnableAllServices", "messageData": [], "message": "Enabling all services.", "timestamp": 1505245693213, "status": "Succeeded" }, { "step": "StartAllServices", "messageData": [], "message": "Waiting for the services to start.", "timestamp": 1505245693220, "status": "Running" }, { "step": "StartAllServices", "messageData": [], "message": "Waiting for the services to start.", "timestamp": 1505245853011, "status": "Succeeded" } ], "doneSteps": 4, "totalSteps": 4 }, "jobType": "RestartServerJob", "createdAt": 1505245656450, "updatedAt": 1505245853073, "statusMessageData": [], "jobTimeout": 1800, "worker": "node1", "completedAt": 1505245853073, "statusMessage": "This job completed successfully." } } ``` ### Cancel an async job Cancel an async job that is currently running. ``` PUT /asyncJob//cancel ``` #### Request path parameters `jobId` Required. ID of the async job to cancel. To view a list of available job IDs, see [List async jobs](#list-async-jobs). #### Response status code 200 OK #### Response body example ``` { "asyncJob": { "id": 2, "args": "{\"withNetstatInfo\":false,\"withPostgresqlData\":false,\"withLatestDump\":false,\"minimumDate\":[2017,6,7],\"node\":\"node1\"}", "progress": -1, "status": "Cancelled", "statusMessageData": [], "detailedProgress": { "progressNotes": [], "doneSteps": 0, "totalSteps": 0 }, "jobType": "ZiplogsJob", "createdAt": 1497029422819, "updatedAt": 1497029433156, "jobTimeout": 1800, "completedAt": 1497029433156, "statusMessage": "This job has been cancelled." } } ``` * * * ## Backup Create backup files. ### Create a backup file Create a backup and save it to a file in the data directory. ``` POST /backupFixedFile ``` #### Request query parameters `jobTimeoutSeconds` Optional. The timout length in seconds. Default is 1800 seconds. `skipVerification` Optional. Whether to verify the integrity of the database backup. `writepath` Required. The name for the backup file. Backup files are placed in the data directory. By default, you can find backup files in the following location: ``` /var/opt/tableau/tableau_server/data/tabsvc/files/backups ``` #### Response status code 200 OK #### Response body example ``` { "asyncJob": { "args": "{\"node\":\"node1\",\"origin\":\"OTHER\",\"overrideDiskSpaceCheck\":false,\"writePath\":\"backupname\",\"skipVerification\":false}", "progress": -1, "id": 8, "status": "Created", "detailedProgress": { "progressNotes": [], "doneSteps": 0, "totalSteps": 0 }, "jobType": "GenerateBackupJob", "createdAt": 1497043142444, "updatedAt": 1497043142444, "statusMessageData": [], "jobTimeout": 86400, "statusMessage": "This job is queued." } } ``` * * * ## Bootstrap Get information about the controller so that you can connect to it. ### Get bootstrap information Get information about the controller, including the controller location and TSM certificate. ``` GET /bootstrap ``` #### Response status code 200 OK #### Response body example ``` { "initialBootstrapSettings": { "port": 8850, "certificate": "", "clusterId": "tabsvc-clusterid", "nodeId": "", "configurationName": "tabsvc", "machineAddress": "", "cryptoEnabled": true, "cryptoKeyStore": "" } } ``` * * * ## Configuration Get information about server configurations, compare configurations, request configuration changes, and apply configuration changes. Server configurations can be viewed and changed in one of two ways: - **Keys**. Tableau Server uses key:value pairs to monitor and manage the server configuration. For a list of configuration keys (or “options”), see [tsm configuration set Options](https://help.tableau.com/v10.4/serverlinux/en-us/cli_configuration-set_tsm.htm). - **Entities**. Entities provide a structured, strongly-typed way to monitor and update server configuration. For a list of entities, see [Entity Definitions and Templates](https://help.tableau.com/v10.5/serverlinux/en-us/entity_library.htm). ### List configurations Get information about the configuration versions available. ``` GET /configurations ``` #### Response status code 200 OK #### Response body example Note: In the following response body example, the values that follow `"name"` (for example, `1`, `2`) are used in other `/configurations` endpoints for the request path parameter. ``` { "links": { "items": [{ "name": "1", "href": "/api/0.5/configurations/1" }, { "name": "2", "href": "/api/0.5/configurations/2" }, { "name": "0", "href": "/api/0.5/configurations/0" }, { "name": "requested", "href": "/api/0.5/configurations/requested" }, { "name": "pending", "href": "/api/0.5/configurations/pending" }] } } ``` ### Get all keys for a configuration version Get the complete server configuration, including all keys and values, for a specific configuration version. ``` GET /configurations//keys ``` #### Request path parameters `config-version` Required. The configuration version. #### Response status code 200 OK #### Response body example The response body shows all keys for the configuration version. Because this response body is thousands of lines, it is not provided here. ### Get a key and value for a configuration version Get a key and the corresponding value for a specified configuration version. ``` GET /configurations//keys/ ``` #### Request path parameters `config-version` Required. The configuration version. `keyId` Required. The key to retrieve from the specified configuration version. #### Response status code 200 OK #### Response body example ``` { "configKeys": { "backgrounder.querylimit": 7200 } } ``` ### Get all entities for a configuration version Get the complete server configuration, represented as a set of entities, for a specific configuration version. ``` GET /configurations//entities ``` #### Request path parameters `config-version` Required. The configuration version. #### Response status code 200 OK #### Response body example ``` { "links": { "items": [ { "name": "bootstrap", "href": "/api/0.5/configurations/7/entities/bootstrap" }, { "name": "crashReporterSettings", "href": "/api/0.5/configurations/7/entities/crashReporterSettings" }, { "name": "customization", "href": "/api/0.5/configurations/7/entities/customization" }, { "name": "gatewaySettings", "href": "/api/0.5/configurations/7/entities/gatewaySettings" }, { "name": "identityStore", "href": "/api/0.5/configurations/7/entities/identityStore" }, { "name": "kerberosSettings", "href": "/api/0.5/configurations/7/entities/kerberosSettings" }, { "name": "mutualSSLSettings", "href": "/api/0.5/configurations/7/entities/mutualSSLSettings" }, { "name": "nonAdminUsernamePasswordSettings", "href": "/api/0.5/configurations/7/entities/nonAdminUsernamePasswordSettings" }, { "name": "openIDSettings", "href": "/api/0.5/configurations/7/entities/openIDSettings" }, { "name": "repositorySSL", "href": "/api/0.5/configurations/7/entities/repositorySSL" }, { "name": "runAsUser", "href": "/api/0.5/configurations/7/entities/runAsUser" }, { "name": "samlSettings", "href": "/api/0.5/configurations/7/entities/samlSettings" }, { "name": "sapHanaSettings", "href": "/api/0.5/configurations/7/entities/sapHanaSettings" }, { "name": "sspiSettings", "href": "/api/0.5/configurations/7/entities/sspiSettings" }, { "name": "trustedAuthenticationSettings", "href": "/api/0.5/configurations/7/entities/trustedAuthenticationSettings" } ] } } ``` ### Get an entity for a configuration version Get the details for a specific entity for a specific configuration version. ``` GET /configurations//entities/ ``` #### Request path parameters `config-version` Required. The configuration version. `entityId` Required. The unique string identifier (for example, `gatewaySettings`) for the entity. #### Response status code 200 OK #### Response body example ``` { "configEntity": { "_type": "gatewaySettingsType", "port": 80, "sslPort": 443, "firewallOpeningEnabled": true, "publicHost": "localhost", "publicPort": 80, "sslEnabled": false, "sslRedirectEnabled": true, "trustedIPs": [], "trustedHosts": [] } } ``` ### Get the difference between two configuration versions by keys Gets the difference between one server configuration version and another, showing any keys and values that changed between those configuration versions. ``` GET /configurations//keys/diff/ ``` #### Request path parameters `from-config-version` Required. The first configuration that is used for comparison. `to-config-version` Required. The second configuration that is used for comparison. #### Response status code 200 OK #### Response body example ``` { "configKeys": { "config.timestamp": "2017-09-11T23:40:11.113", "gateway.public.host": "localhost", "gateway.trusted": "", "gateway.trusted_hosts": "" } } ``` ### Get the difference between two configuration versions by entities Gets the difference between one server configuration version and another, showing any entities that changed between those configuration versions. ``` GET /configurations//entities/diff/ ``` #### Request path parameters `from-config-version` Required. The first configuration that is used for comparison. `to-config-version` Required. The second configuration that is used for comparison. #### Response status code 200 OK #### Response body example ``` { "configEntities": { "gatewaySettings": { "_type": "gatewaySettingsType", "publicHost": "localhost", "trustedIPs": [], "trustedHosts": [] } } } ``` ### Get the most recent configuration version number Gets the version number of the most recent server configuration. ``` GET /configurations/requested/version ``` #### Response status code 200 OK #### Response body example ``` { "version": "17" } ``` ### Update configuration keys in the pending configuration Updates the values associated with one or more configuration keys in the pending configuration. To make the pending configuration take effect, you must call [`POST /configurations/pending/promote`](#update-tableau-server-with-the-pending-configuration). ``` PATCH /configurations/pending/keys ``` #### Request body example ``` { "configKeys": { "licensing.tries": 6 } } ``` #### Response status code 204 No Content ### Update an entity in the pending configuration Update a configuration entity in the pending configuration. To make the pending configuration take effect, you must call [`POST /configurations/pending/promote`](#update-tableau-server-with-the-pending-configuration). ``` PUT /configurations/pending/entities/ ``` #### Request path parameters `entityName` Required. The name of the entity that will be updated. For a list of entity names, call [`GET /configurations//entities`](#get-all-entities-for-a-configuration-version). For example, you could use this parameter to update the `gatewaySettings` entity. #### Request body example The request body consists of the same JSON elements returned by [`GET /configurations//entities/`](#get-an-entity-for-a-configuration-version) for the specified configuration entity. ``` { "configEntity": { "_type": "gatewaySettingsType", "port": 80, "firewallOpeningEnabled": true, "publicHost": "localhost", "publicPort": 80, "sslEnabled": false, "sslRedirectEnabled": true, "trustedIPs": [], "trustedHosts": [], "sslPort": 443 } } ``` #### Response status code 204 No Content ### Update Tableau Server with the pending configuration Updates Tableau Server with the pending configuration. The response body provides the latest configuration version number. ``` POST /configurations/pending/promote ``` #### Response status code 200 OK #### Response body example ``` { "version": "19" } ``` ### Delete a configuration version Deletes the specified configuration version. Subsequent configuration version numbers will remain unchanged, resulting in gaps in the configuration version sequence. So if you delete configuration version `9`, configuration version `10` retains the same version number that it did previous to using this endpoint. This command takes effect immediately and does not restart Tableau Server. ``` DELETE /configurations/ ``` #### Request path parameters `config-version` Required. The configuration version to delete. #### Response status code 200 OK ### Delete a key from the pending configuration Deletes the specified key from the pending configuration. To make the pending configuration take effect, call [`POST /configurations/pending/promote`](#update-tableau-server-with-the-pending-configuration). ``` DELETE /configurations/pending/keys/ ``` #### Request path parameters `keyId` Required. The name or ID of the key to be deleted. #### Response status code 200 OK ### Delete an entity from the pending configuration Deletes the contents of the specified entity from the pending configuration. To make the pending configuration take effect, call [`POST /configurations/pending/promote`](#update-tableau-server-with-the-pending-configuration). ``` DELETE /configurations/pending/entities/ ``` #### Request path parameters `entityId` Required. The name or ID of the entity that will have its contents deleted. #### Response status code 200 OK * * * ## Coordination Service These endpoints are used to manage the Tableau Coordination Service, which is built on the open-source Apache Zookeeper project. To learn more about the Coordination Service, see [Deploy a Coordination Service Ensemble](https://help.tableau.com/v10.5/serverlinux/en-us/distrib_ha_zk_linux.htm). ### Cleanup Coordination Service Deletes the previously-used coordination service ensemble. Tableau Server cannot be running when you use this command, so you must call [POST /disable](#disable-services) before running this command. ``` POST /cleanupzk ``` #### Response status code 200 OK #### Response body example ``` { "asyncJob": { "progress": 0, "id": 36, "status": "Running", "detailedProgress": { "progressNotes": [], "doneSteps": 0, "totalSteps": 1 }, "jobType": "CleanupZooKeeperJob", "createdAt": 1506727631431, "updatedAt": 1506727631445, "statusMessageData": [], "jobTimeout": 1200, "worker": "node1", "statusMessage": "This job is currently running." } } ``` ### Switch Coordination Service ensembles Switches Tableau Server to the new Coordination Service ensemble. Tableau Server cannot be running when you use this command, so you must call [POST /disable](#disable-services) before running this command. ``` POST /togglezk ``` #### Response status code 200 OK #### Response body example ``` { "asyncJob": { "progress": -1, "id": 28, "status": "Created", "detailedProgress": { "progressNotes": [], "doneSteps": 0, "totalSteps": 0 }, "jobType": "CleanupZooKeeperJob", "createdAt": 1506724940676, "updatedAt": 1506724940676, "statusMessageData": [], "jobTimeout": 1200, "statusMessage": "This job is queued." } } ``` ### Deploy Coordination Service ensemble to server cluster nodes Deploys the Coordination Service ensemble to one or more cluster nodes. Tableau Server cannot be running when you use this command, so you must call [POST /disable](#disable-services) before running this command. ``` POST /reconfigzk ``` #### Request query parameters `nodes` Optional. A comma-separated list of node names that designates which nodes the Coordination Service ensemble should be deployed to. For example, you might enter `nodes=node2`. #### Response status code 200 OK * * * ## Enable Enable Tableau Server services. ### Enable services Enable all Tableau Server services. (This starts Tableau Server.) ``` POST /enable ``` #### Response status code 200 OK #### Response body example ``` { "asyncJob": { "progress": -1, "id": 5, "status": "Created", "detailedProgress": { "progressNotes": [], "doneSteps": 0, "totalSteps": 0 }, "jobType": "StartServerJob", "createdAt": 1497041247933, "updatedAt": 1497041247933, "statusMessageData": [], "jobTimeout": 480, "statusMessage": "This job is queued." } } ``` * * * ## Disable Disable Tableau Server services. ### Disable services Disable all Tableau Server services. This stops Tableau Server until you call the [Enable services endpoint](#enable-services). ``` POST /disable ``` #### Response status code 200 OK #### Response body example ``` { "asyncJob": { "progress": -1, "id": 4, "status": "Created", "detailedProgress": { "progressNotes": [], "doneSteps": 0, "totalSteps": 0 }, "jobType": "StopServerJob", "createdAt": 1497041247933, "updatedAt": 1497041247933, "statusMessageData": [], "jobTimeout": 300, "statusMessage": "This job is queued." } } ``` * * * ## Restart Restart Tableau Server services. ### Restart services Restart all Tableau Server services. This causes Tableau Server downtime while all services restart. ``` POST /restart ``` #### Response status code 200 OK #### Response body example ``` { "asyncJob": { "progress": 0, "id": 26, "status": "Running", "detailedProgress": { "progressNotes": [ { "step": "DisableAllServices", "messageData": [], "message": "Disabling all services.", "timestamp": 1506724565632, "status": "Running" } ], "doneSteps": 0, "totalSteps": 4 }, "jobType": "RestartServerJob", "createdAt": 1506724565614, "updatedAt": 1506724565632, "statusMessageData": [], "jobTimeout": 600, "worker": "node1", "statusMessage": "This job is currently running." } } ``` * * * ## Initialize Initialize Tableau Server. * * * ### Initialize Tableau Server Initializes Tableau Server after any pending changes to the configuration have been applied by calling [`POST /configurations/pending/promote`](#update-tableau-server-with-the-pending-configuration). ``` POST /initialize ``` #### Request query parameters `configurationVersion` Optional. Specifies a specific version of the server configuration that should be used to initialize Tableau Server. `force` Optional. If set to `true`, override an error if Tableau Server has already been initialized. `jobTimeoutSeconds` Optional. Overrides the default timeout with the number of seconds provided. `startServer` Optional. If set to `true`, start Tableau Server after initializing. #### Response status code 200 OK #### Response body example ``` { "asyncJob": { "args": "{\"startServer\":true}", "progress": 0, "id": 42, "status": "Running", "detailedProgress": { "progressNotes": [], "doneSteps": 0, "totalSteps": 25 }, "jobType": "InitializeServerJob", "createdAt": 1506737181826, "updatedAt": 1506737181845, "statusMessageData": [], "jobTimeout": 1620, "worker": "node1", "statusMessage": "This job is currently running." } } ``` * * * ## File store Make the file store writeable or write-only in preparation for node and process changes. ### Decommission the file store Set the file store to read-only. ``` POST /filestore/decommission ``` #### Request query parameters `nodes` Optional. A comma-separated list of node names that designates which nodes have file stores to decommission. If the nodes are not specified, TSM compares the staged topology to the live topology to determine which nodes are trying to remove the file store, and then adds those nodes to the decommission list. For example, you might enter `nodes=node1`. #### Response status code 200 OK #### Response body example ``` { "asyncJob": { "args": "{\"hostnameList\":[\"node1\"],\"noFailureOnHAWarnings\":false}", "progress": -1, "id": 11, "status": "Created", "detailedProgress": { "progressNotes": [], "doneSteps": 0, "totalSteps": 6 }, "jobType": "DecommissionFilestoreJob", "createdAt": 1497058498658, "updatedAt": 1497058498664, "statusMessageData": [], "jobTimeout": 300, "statusMessage": "This job is queued." } } ``` ### Recommission the file store Make the file store writeable. ``` /filestore/recommission ``` #### Request query parameters `nodes` Required. A comma-separated list of node names that designates which nodes have file stores to decommission. For example, you might enter `nodes=node1`. #### Response status code 204 No Content * * * ## Licensing ### Activate product trial license Activate a limited-time product trial license. ``` POST /licensing/activateTrial ``` #### Response status code 204 No Content ### Activate product key Activate a product key. ``` POST /licensing/productKeys/ ``` #### Request path parameters `key` The product key to activate. #### Response status code 201 Created #### Response body example ``` { "productKeys": { "items": [ { "valid": true, "expiration": "2017-11-01T12:00:00.158Z", "maintenance": "2017-11-01T12:00:00.157Z", "guestAllowed": true, "serial": "" } ] } } ``` ### Refresh all product keys Refreshes all product keys. To learn more about refreshing product keys, see [Refresh Maintenance Date for the Product Key](https://help.tableau.com/current/server/en-us/license_refresh.htm). ``` POST /licensing/resync ``` #### Response status code 204 No Content ### Get licensing information Get a list of API endpoints related to licensing that are relevant to the current Tableau Server installation. ``` GET /licensing ``` #### Response status code 200 OK #### Response body example ``` { "links": { "items": [ { "name": "collection", "href": "/api/0.5/licensing/productKeys" }, { "name": "item", "href": "/api/0.5/licensing/productKeys/{serial}" }, { "name": "related", "href": "/api/0.5/licensing/resync" }, { "name": "related", "href": "/api/0.5/licensing/activateTrial" }, { "name": "related", "href": "/api/0.5/licensing/registration" } ] } } ``` ### List product keys List the product keys that have been activated. ``` GET /licensing/productKeys ``` #### Response status code 200 OK #### Response body example ``` { "productKeys": { "items": [ { "expiration": "2017-11-01T12:00:00.000Z", "valid": true, "numCores": 16, "serial": "example-serial-number-here", "maintenance": "2017-11-01T12:00:00.000Z", "guestAllowed": true } ] } } ``` ### Get product key details Get information about a product key that has been activated. ``` GET /licensing/productKeys/ ``` #### Request path parameters `serial` Required. The product key serial number. #### Response status code 200 OK #### Response body example ``` { "productKeys": { "items": [ { "expiration": "2017-11-01T12:00:00.000Z", "valid": true, "numCores": 16, "serial": "example-serial-number-here", "maintenance": "2017-11-01T12:00:00.000Z", "guestAllowed": true } ] } } ``` ### Delete a product key Delete the specified product keys. ``` DELETE /licensing/productKeys/ ``` #### Request path parameters `serial` Required. The product key serial number. #### Response status code 204 No Content ### Get registration information Get information on product registration. ``` GET /licensing/registration ``` #### Response status code 200 OK #### Response body example This method returns the following response body if registration has already occurred: ``` { "registration": { "fields": [], "needToRegister": false } } ``` This method returns the following response body if registration is still required. This response body provides a template that you can complete and pass to [POST /licensing/registration](#register-tableau-server) to complete registration. ``` { "registration": { "fields": [ { "key": "first_name", "value": "" }, { "key": "last_name", "value": "" }, { "key": "email", "value": "" }, { "key": "company", "value": "" }, { "key": "title", "value": "" }, { "key": "department", "value": "" }, { "key": "industry", "value": "" }, { "key": "phone", "value": "" }, { "key": "city", "value": "" }, { "key": "state", "value": "" }, { "key": "zip", "value": "" }, { "key": "country", "value": "" } ], "type": "STANDARD", "needToRegister": true } } ``` ### Register Tableau Server Register Tableau Server, providing information that includes the name, company and contact information of the user who is registering the product. ``` POST /licensing/registration ``` #### Request body example ``` { "registration": { "fields": [ { "key": "first_name", "value": "Mary" }, { "key": "last_name", "value": "Smith" }, { "key": "email", "value": "marysmith@examplecompany.com" }, { "key": "company", "value": "The Example Company" }, { "key": "title", "value": "CEO" }, { "key": "department", "value": "Executive" }, { "key": "industry", "value": "Internet" }, { "key": "phone", "value": "5555555555" }, { "key": "city", "value": "Anytown" }, { "key": "state", "value": "WA" }, { "key": "zip", "value": "98033" }, { "key": "country", "value": "USA" } ], "type": "STANDARD", "needToRegister": true } } ``` #### Response status code 204 No Content ### Get offline activation XML from product key Get XML that you can use for offline activation. To learn more about offline activation, see [Install Tableau Server in a Disconnected (Air-Gapped) Environment](http://help.tableau.com/v10.5/server-linux/en-us/install_air_gapped.htm). ``` GET /licensing/offline/activationRequest/ ``` #### Response status code 204 No Content #### Response body example ``` 3 ACTIVATION SOME-PRODU-CTKE-YHERE 0 Not Applicable 4073728 11.14.1 1 1 1212466702754 SRV A05A4257F9F138A9FF9176A980F9DECE7AC86A68 OK x64_lsb none 1 2 F0D038624F02B5B00D7436D390EBE11CEF84BB61 4 3 flexFulfillmentVersion 1 pubExpiry 31-dec-2029 pubAct 0 pubActOd 0 pubConc 1 pubConcOd 0 pubHyb 0 pubHybOd 0 pubRepairCount 0 OFFLINE true 12345678910112 1 ``` ### Activate offline Activate Tableau Server in an offline (air-gapped) environment, passing the contents of the `activation.tlf` file provided by the [Tableau Offline Activation](http://www.tableau.com/support/drivers/activation) website as the request body. To learn more about offline activation, see [Install Tableau Server in a Disconnected (Air-Gapped) Environment](http://help.tableau.com/v10.5/server-linux/en-us/install_air_gapped.htm). ``` POST /licensing/offline/activationRequest ``` Note: The `POST` request must use the `multipart form-data` type and must pass the `activation.tlf` file as the value for the `file` key. #### Request body example ``` 3ACTIVATION XXXX-XXXX-XXXX-XXXX-XXXX 0 Not Applicable4073728 XX.XX.X1 x64_lsb none 1XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX 2XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX 4 X flexFulfillmentVersion 1 pubExpiry 31-dec-2029 pubAct 0 pubActOd 0 pubConc 1 pubConcOd 0 pubHyb 0 pubHybOd 0 pubRepairCount 0 OFFLINE true XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX1 ``` #### Response status code 200 OK ### Get offline deactivation file Get a file (`deactivate.tlq`) that you can use to deactivate a Tableau Server product key on a server that is not connected to the internet. To complete product deactivation, You must pass the `deactivate.tlq` file to the [Tableau Activation](https://www.tableau.com/support/activation) website from a computer with an internet connection, download the `return.tlr` file, and then pass it to the [`POST /licensing/offline/deactivationRequest`](#deactivate-offline) method. ``` GET /licensing/offline/deactivationRequest/ ``` #### Request path parameters `product-key` The Tableau Server product key that you are deactivating. #### Response status code 200 OK #### Response body example The response body is the contents of the `deactivate.tlq` file, formatted as XML. ### Deactivate offline Use the `return.tlq` file to complete offline deactivation of Tableau Server. The `return.tlq` file is provided by the [Tableau Activation](https://www.tableau.com/support/activation) website when you provide a deactivation file (`offline.tlq`) generated using the [`GET /licensing/offline/deactivationRequest/`](#get-offline-deactivation-file) method. ``` POST /licensing/offline/deactivationRequest ``` #### Request body parameters The request body must use the `multipart form-data` type. `file` Required. A `return.tlf` file. #### Response status code 200 OK ### Get offline licensing properties Get properties that pertain to offline licensing of Tableau Server. ``` GET /licensing/offline/properties ``` #### Response status code 200 OK #### Response body example ``` { "offlineLicensingProperties": { "trustedStorageInitialized": true, "finalActivationFileCreated": false, "initialActivationFileCreated": false, "deactivationFileCreated": false } } ``` * * * ## Login Log in to TSM. ### Log in Log in to TSM and get an authentication cookie that can be used for additional requests. ``` POST /login ``` #### Request body parameters - `user_name`. The user name of a user that has access to TSM. - `password`. The password of a user that has access to TSM. #### Request body example ``` { "authentication": { "name": "", "password":"" } } ``` #### Response status code 204 No Content * * * ## Logout Log out of TSM. ### Log out Invalidate the authentication cookie for the current session. ``` POST /logout ``` #### Response status code 200 ### Log out all users Invalidate the authentication cookies of all sessions. ``` POST /logout/all ``` #### Response status code 200 * * * ## Nodes Get information about nodes, add nodes, and remove nodes. ### List nodes List the nodes in the Tableau Server cluster. ``` GET /nodes ``` #### Response status code 200 OK #### Response body example ``` { "clusterNodes": { "nodes": [ "node1" ] } } ``` ### Get node information by node ID Get information about a node, including the node’s address, configuration version, topology version, and more. The network addresses returned in the `addresses` list are accessible from the initial node, but not necessarily from other computers on your network, and are not returned in a predetermined order. ``` GET /nodes/ ``` #### Request path parameters `nodeId` Required. The node ID. Note that node IDs are distinct from the computer address. For example, the node ID might be `node1`. #### Response status code 200 OK #### Response body example ``` { "nodeInfo": { "address": "localhost", "status": "NONE", "roles": [], "configurationVersion": "2", "topologyVersion": "3", "addresses": [ "tableau-server", "10.10.10.6" ], "processorCount": 8, "availableMemory": 15887 } } ``` ### Get topology defaults for a node Get information about the topology defaults that are used when a new node is created. Topology defaults determine how many instances of each service exist on the nodes in a server topology, and are set according to the number of processors and the memory available on a given node. The response body example shown below shows the node topology defaults for a node with less than 32GB of memory available. ``` GET /nodes//defaults/topology ``` #### Request path parameters `nodeId` Required. The node ID. Note that node IDs are distinct from the computer address. For example, the node ID might be `node1`. #### Response status code 200 OK #### Response body example ``` { "topologyDefaults": { "serviceDefaults": [ { "name": "clustercontroller", "instanceCount": 1 }, { "name": "backgrounder", "instanceCount": 1 }, { "name": "cacheserver", "instanceCount": 1 }, { "name": "dataserver", "instanceCount": 1 }, { "name": "vizqlserver", "instanceCount": 2 }, { "name": "gateway", "instanceCount": 1 } ] } } ``` ### New node ID Get a unique node ID for a new that you want to create. To actually create the node, you must pass the new node ID to to [Create a node](#create-a-node). ``` POST /nodes ``` #### Response status code 202 Accepted #### Response body example ``` { "nodeId": "node2" } ``` ### Create a node Create a node using an ID provided by [New Node ID](#new-node-id). ``` POST /nodes/ ``` #### Request path parameters `nodeId` The node ID generated by [Get new node ID](#get-new-nodeId). #### Request body parameters `serverAddress` Required. The hostname or IP address of the new node. #### Request body example ``` { "nodeInfo": { "configurationVersion": "1", "topologyVersion": "1", "address": "", "addresses": [""], "roles": [] } } ``` #### Response status code 200 OK #### Response body example ``` { "nodeInfo": { "roles": [], "addresses": [ "tableau-server2" ], "status": "NONE", "topologyVersion": "1", "configurationVersion": "1", "address": "tableau-server2" } } ``` * * * ## Repository Get information about the repository and configure fail over. ### Get current master repository information Get information about the node that hosts the master repository. ``` GET /repository/currentMaster ``` #### Response status code 200 OK #### Response body example ``` { "repositoryNodeInfo": { "hostName": "localhost", "port": 8060, "nodeState": "AVAILABLE" } } ``` ### Check if a repository is safe to remove Determine whether a repository can be safely removed. ``` GET /repository/isSafeToRemove ``` #### Request query parameters `host` Required. The hostname of the node with the repository. For example, you might enter `host=localhost`. #### Response status code 200 OK #### Response body example ``` { "isRepositorySafeToRemove": false } ``` ### Fail over repository to another PostgreSQL node Fail over to the specified, preferred, or next available PostgresSQL node. Although all request query parameters are optional, you must specify a value for either the `target` parameter or the `preferred` parameter. ``` GET /repository/failover ``` #### Request query parameters `jobTimeoutSeconds` Optional. The number of seconds provided before the job times out. `target` Optional. The hostname of the node to fail over to. For example, you might enter `target=localhost`. `preferred` Optional. This boolean value can be set to `true` to fail over to the node specified by the `pgsql.preferred_host` configuration key. #### Response status code 200 OK #### Response body example ``` { "asyncJob": { "args": "{\"target\":\"localhost\",\"isPreferredHostUsed\":false}", "progress": 0, "id": 40, "status": "Running", "detailedProgress": { "progressNotes": [ { "step": "SendFailoverCommand", "messageData": [], "message": "Initiating repository failover.", "timestamp": 1506735366078, "status": "Running" } ], "doneSteps": 0, "totalSteps": 2 }, "jobType": "RepositoryFailover", "createdAt": 1506735366056, "updatedAt": 1506735366078, "statusMessageData": [], "jobTimeout": 600, "worker": "node1", "statusMessage": "This job is currently running." } } ``` ### Enable repository access by an external user Enable access to the repository by an external user, including the built-in _tableau_ user account. **Caution**: Calling this endpoint causes an immediate restart of Tableau Server, resulting in downtime during that restart. ``` PUT /repository/externalUsers/ ``` #### Request path parameters `nickName` Required. The nickname of the external user account to enable. For example, you could use `tableau` for this parameter. #### Request query parameters `jobTimeoutSeconds` Optional. The number of seconds provided before the job times out. #### Request body parameters `externalRepositoryPassword` Required. The password for the external user account. For example, to set the password for the user to `myexamplepassword`, you would pass the following request body: ``` { "externalRepositoryPassword": { "password": "myexamplepassword" } } ``` #### Response status code 200 OK #### Response body example ``` { "asyncJob": { "args": "{\"usersAndPasswordsToUpdate\":{\"REMOTE\":\"mypassword\"}}", "progress": -1, "id": 3, "status": "Created", "detailedProgress": { "progressNotes": [], "doneSteps": 0, "totalSteps": 0 }, "jobType": "UpdateRepositoryUsersJob", "createdAt": 1507050583775, "updatedAt": 1507050583775, "statusMessageData": [], "jobTimeout": 1320, "statusMessage": "This job is queued." } } ``` ### Disable repository access for an external user Disable access to the repository by an external user, including the built-in _tableau_ user account. **Caution**: Calling this endpoint causes an immediate restart of Tableau Server, resulting in downtime during that restart. ``` DELETE /repository/externalUsers/ ``` #### Request path parameters `nickName` Required. The nickname of the external user account to enable. For example, you could use `tableau` for this parameter. #### Request query parameters `jobTimeoutSeconds` Optional. The number of seconds provided before the job times out. #### Response status code 200 OK #### Response body example ``` { "asyncJob": { "args": "{\"usersToDisable\":[\"REMOTE\"]}", "progress": -1, "id": 5, "status": "Created", "detailedProgress": { "progressNotes": [], "doneSteps": 0, "totalSteps": 0 }, "jobType": "UpdateRepositoryUsersJob", "createdAt": 1507050638864, "updatedAt": 1507050638864, "statusMessageData": [], "jobTimeout": 1320, "statusMessage": "This job is queued." } } ``` * * * ## Restore Restores Tableau Server from a backup. ### Restore Restore Tableau Server from the specified backup file. ``` POST /restoreFixedFile ``` #### Request query parameters `fixedFile` Required. The name of the backup file in the data directory. By default, you can find backup files in the following location: ``` /var/opt/tableau/tableau_server/data/tabsvc/files/backups ``` `jobTimeoutSeconds` Optional. The timout length in seconds. Default is 1800 seconds. `no-config` Optional. Restore the database but not the server configuration. Default is false. `restart` Optional. Restart Tableau Server after restoring. Default is false. `no-topology` Optional. Restore the database but not the server topology (the process configuration for nodes). Default is false. #### Response status code 200 OK #### Response body example ``` { "asyncJob": { "args": "{\"noConfig\":false,\"restart\":false,\"uploaded\":false,\"noTopology\":false,\"tsbakPath\":\"/var/opt/tableau/tableau_server/data/tabsvc/files/backups/backupname\"}", "progress": -1, "id": 12, "status": "Created", "detailedProgress": { "progressNotes": [], "doneSteps": 0, "totalSteps": 22 }, "jobType": "RestoreJob", "createdAt": 1497059398055, "updatedAt": 1497059398070, "statusMessageData": [], "jobTimeout": 172800, "statusMessage": "This job is queued." } } ``` * * * ## Reindex search Re-create the Tableau Server search index. ### Reindex search Re-create the Tableau Server search index. ``` POST /reindex-search ``` #### Request query parameters `jobTimeoutSeconds` Optional. The timout length in seconds. Default is 3600 seconds. #### Response status code 200 OK #### Response body example ``` { "asyncJob": { "args": "{\"startServer\":true}", "progress": 0, "id": 13, "status": "Running", "detailedProgress": { "progressNotes": [], "doneSteps": 0, "totalSteps": 2 }, "jobType": "RebuildSearchIndex", "createdAt": 1497060232637, "updatedAt": 1497060232646, "statusMessageData": [], "jobTimeout": 900, "worker": "node1", "statusMessage": "This job is currently running." } } ``` * * * ## Server information Get information about Tableau Server. ### Get server information Get the version, initialization state, licensing state, and operating system of Tableau Server. This is the only TSM endpoint that does not require authentication. ``` GET /serverInfo ``` #### Response status code 200 OK #### Response body example ``` { "serverInfo": { "serverVersion": "", "initializationState": "Initialized", "operatingSystem": "Linux", "licensingState": "Licensed" } } ``` ### Get support information Get the operating system, server version, and locale of Tableau Server. ``` GET /supportInfo ``` #### Response status code 200 OK #### Response body example ``` { "supportInfo": { "operatingSystem": "Linux", "serverVersion": "", "locale": "en-us" } } ``` * * * ## Settings Export and import configuration and topology settings. ### Export configuration and topology settings Export the current configuration and topology settings, either as a response body, or as a file. The configuration settings are exported as configuration keys, rather than entities. ``` GET /export ``` #### Request query parameters `formatAsFile` Optional. A boolean value that determines whether to return the exported configuration and topology settings as a file or as a response body. The default value for this parameter is `false`. `includeBinaryVersion` Optional. A boolean value that determines whether to include a build number in the configuration and topology settings. This build number is required by the [`POST /import`](#import-configuration-and-topology-settings) method if the request body includes `topologyVersion`. The default value for this parameter is `false`. #### Response status code 200 OK #### Response body example ``` { "topologyVersion": { "nodes": { "node1": { "services": { "vizportal": { "instances": [ { "instanceId": "0", "binaryVersion": "10500.17.1217.1935" } ] }, "backgrounder": { "instances": [ { "instanceId": "0", "binaryVersion": "10500.17.1217.1935" } ] }, "licenseservice": { "instances": [ { "instanceId": "0", "binaryVersion": "10500.17.1217.1935" } ] }, "tabadminagent": { "instances": [ { "instanceId": "0", "binaryVersion": "10500.17.1217.1935" } ] }, "cacheserver": { "instances": [ { "instanceId": "0", "binaryVersion": "10500.17.1217.1935" } ] }, "tabsvc": { "instances": [ { "instanceId": "0", "binaryVersion": "10500.17.1217.1935" } ] }, "clustercontroller": { "instances": [ { "instanceId": "0", "binaryVersion": "10500.17.1217.1935" } ] }, "gateway": { "instances": [ { "instanceId": "0", "binaryVersion": "10500.17.1217.1935" } ] }, "pgsql": { "instances": [ { "instanceId": "0", "binaryVersion": "10500.17.1217.1935" } ] }, "tabadmincontroller": { "instances": [ { "instanceId": "0", "binaryVersion": "10500.17.1217.1935" } ] }, "samlservice": { "instances": [ { "instanceId": "0", "binaryVersion": "10500.17.1217.1935" } ] }, "filestore": { "instances": [ { "instanceId": "0", "binaryVersion": "10500.17.1217.1935" } ] }, "databasemaintenance": { "instances": [ { "instanceId": "0", "binaryVersion": "10500.17.1217.1935" } ] }, "vizqlserver": { "instances": [ { "instanceId": "0", "binaryVersion": "10500.17.1217.1935" } ] }, "searchserver": { "instances": [ { "instanceId": "0", "binaryVersion": "10500.17.1217.1935" } ] }, "appzookeeper": { "instances": [ { "instanceId": "0", "binaryVersion": "10500.17.1217.1935" } ] }, "dataserver": { "instances": [ { "instanceId": "0", "binaryVersion": "10500.17.1217.1935" } ] }, "hyper": { "instances": [ { "instanceId": "0", "binaryVersion": "10500.17.1217.1935" } ] }, "backuprestore": { "instances": [ { "instanceId": "0", "binaryVersion": "10500.17.1217.1935" } ] }, "siteimportexport": { "instances": [ { "instanceId": "0", "binaryVersion": "10500.17.1217.1935" } ] } } } } }, "configKeys": { "endpoints.health.enabled": true, "config.version": 18, "tableau_projects.language": "en", "endpoints.enabled": false } } ``` ### Import configuration and topology settings Import the current configuration and/or topology settings. The request body can include either configuration keys (`configKeys`) or configuration entities (`configEntities`). This method changes the pending configuration and/or topology, so to apply changes, you need to call one or both of the following methods: - [POST /configurations/pending/promote](#update-tableau-server-with-the-pending-configuration) - [POST /topologies/pending/promote](#update-tableau-server-with-the-pending-topology) ``` POST /import ``` #### Request query parameters `configuration` Optional. Set this boolean value to `false` to ignore the configuration settings in the request body. The default value is `true`. `topology` Optional. Set this boolean value to `false` to ignore the configuration settings in the request body. The default value is `true`. #### Request body example The following is a request body that only includes a single configuration entity: ``` { "configEntities": { "gatewaySettings": { "_type": "gatewaySettingsType", "port": 80, "sslRedirectEnabled": true, "publicHost": "localhost", "publicPort": 80 } } } ``` A request body can also include topology settings (in a `topologyVersion` field). For an example of JSON that includes this field, see the response body for [GET /export](#export-configuration-and-topology-settings). #### Response code 200 OK * * * ## Status Get the status of Tableau Server. ### Get server status Get the status of all nodes and services on Tableau Server. ``` GET /status ``` #### Response status code 200 OK #### Response body example ``` { "clusterStatus": { "nodes": [{ "services": [{ "serviceName": "filestore", "instances": [{ "code": "ACTIVE", "processStatus": "Active", "instanceId": "0", "timestampUtc": 1497060680268, "currentDeploymentState": "Enabled", "binaryVersion": "" }], "rollupStatus": "Running", "rollupRequestedDeploymentState": "Enabled" }, { "..." }], "nodeId": "node1", "rollupStatus": "Running", "rollupRequestedDeploymentState": "Enabled" }], "href": "/api/0.5/status", "rollupStatus": "Running", "rollupRequestedDeploymentState": "Enabled" } } ``` ### Get node status Get the status of all services on a specified node. ``` GET /status/nodes/ ``` #### Request path parameters `nodeId` The node for which you want to get the status. #### Response status code 200 OK #### Response body example ``` { "nodeStatus": { "services": [{ "serviceName": "filestore", "instances": [{ "code": "ACTIVE", "processStatus": "Active", "instanceId": "0", "timestampUtc": 1497061100187, "currentDeploymentState": "Enabled", "binaryVersion": "" }], "rollupStatus": "Running", "rollupRequestedDeploymentState": "Enabled" }, { "..." }], "nodeId": "node1", "rollupStatus": "Running", "rollupRequestedDeploymentState": "Enabled" } } ``` ### Get service status Get the status of all instances of a specified service. ``` GET /status/nodes//services/ ``` #### Request path parameters `nodeId` The node that hosts the service for which you want to get the status. `serviceName` The name of the service for which you want to get the status. #### Response status code 200 OK #### Response body example ``` { "serviceStatus": { "serviceName": "vizqlserver", "instances": [{ "processStatus": "Active", "instanceId": "0", "timestampUtc": 1497061456668, "currentDeploymentState": "Enabled", "binaryVersion": "" }, { "..." }], "rollupStatus": "Running", "rollupRequestedDeploymentState": "Enabled" } } ``` ### Get service instance status Get the status of the specified instance of a service. ``` GET /status/nodes//services// ``` #### Request path parameters `nodeId` The node that hosts the service for which you want to get the status. `serviceName` The name of the service for which you want to get the status. `instanceId` The instance for which you want to get the status. #### Response status code 200 OK #### Response body example ``` { "instanceStatus": { "processStatus": "Active", "instanceId": "0", "timestampUtc": 1497061516688, "currentDeploymentState": "Enabled", "binaryVersion": "" } } ``` * * * ## Sites The TSM API sites methods are used to import and export sites, and to unlock sites. To export and re-import a site, do the following: 1. Export the site using the [`POST /sites//export`](#export-a-site) method. 2. Generate import mapping files using the [`POST /sites//import`](#generate-import-mapping-files) method. 3. Verify that site settings are mapped correctly, and correct any errors. To learn more, see [Verify that site settings are mapped correctly (Linux)](http://help.tableau.com/current/server-linux/en-us/sites_exportimport.htm#verify-site-mappings) or [Verify that site settings are mapped correctly (Windows)](http://help.tableau.com/current/server/en-us/sites_exportimport.htm#verify-site-mappings). 4. Complete the import process using the [`POST /sites//importverified`](#complete-site-import) method. 5. Unlock any sites that were locked due to errors that occurred when exporting or importing a site using the [`POST /sites//unlock`](#unlock-a-site) method. To learn more about exporting and importing a site, see [Export or Import a Site (Linux)](http://help.tableau.com/current/server-linux/en-us/sites_exportimport.htm) or [Export or Import a Site (Windows)](http://help.tableau.com/current/server/en-us/sites_exportimport.htm). * * * #### Locating the siteId The `siteId` is name of the site. You can get the `siteId` from the URL when you’re signed in to the site from a web browser. For example, if only one site exists on the server, that site is named `Default`. When you’re signed in to the Default site, the browser URL looks something like this: ``` https://server-name/#/projects ``` In the URL, the absence of the `/site` parameter indicates that it’s the Default site. The `siteId` for the Default site is `Default`. On a multi-site Tableau Server deployment, the browser URL includes `#/site/` followed by the `siteId`. The following URL would appear if you navigate to the Views page on a site whose `siteId` is `finance`: ``` https://localhost/#/site/finance/views ``` * * * ### Export a site Export a specified Tableau Server site to a .zip file. You can export a site to archive its contents, or to complete the first step in a site migration process. If an error occurs when calling this method, the site will be in a locked state until you call the [`POST /sites//unlock`](#unlock-a-site) method. ``` POST /sites//export ``` #### Request path parameters `siteId` Required. The `siteId` is name of the site. See [Locating the siteId](#locating-the-siteid). #### Request query parameters `bucketName` Optional, unless `storageType` is set to `s3` (for Amazon S3 Storage). The name of the Amazon S3 storage bucket where the resulting site export file is placed. `continueOnIgnorableErrors` Optional. If set to `true`, site export will continue if ignorable errors are encountered. `exportFile` Required. Path to the resulting export file. For export files stored on the local server, the default path must be under the directory defined by the `basefilepath.site_export.exports` configuration setting. On Linux, the default directory is the following: ``` /var/opt/tableau/tableau_server/data/tabsvc/files/siteexports ``` On Windows, the default directory is the following: ``` C:\ProgramData\Tableau\Tableau Server\data\tabsvc\files\siteexports ``` `jobTimeoutSeconds` Optional. The timeout length in seconds. Default is 1800 seconds. `node` Optional. The node ID of the server node that is performing the site export. `overwrite` Optional. If set to `true`, this option will overwrite the site export file. `storageType` Optional. Determines where the resulting export file will be stored. If set to `filesystem` (the default value), the export file is stored on the local server. If set to `s3`, the export file is stored in Amazon S3 storage in the bucket defined by the `bucketName` parameter. #### Request body parameters `remoteStorageEncryptionInfo` Required only if `storageType` is set to `s3` because an Amazon S3 storage bucket is being used to store the export file. The `key` in the request is a base-64 encoded 256-bit AES symmetric key to used to encrypt the export file when uploading it to S3. The same key will be needed to decrypt the file after downloading it and generating import mapping files using [`POST /sites//import`](#generate-import-mapping-files). #### Request body example The following request body is only required if `storageType` is set to `s3` because an Amazon S3 storage bucket is being used to store the export file. ``` { "remoteStorageEncryptionInfo": { "key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" } } ``` #### Response status code 200 OK. #### Response body example ``` { "asyncJob": { "args": "{\"node\":\"node1\",\"siteUrl\":\"test\",\"exportName\":\"DefaultExport.zip\",\"productName\":\"Tableau Server\",\"overwriteExportFile\":false}", "progress": -1, "id": 10, "status": "Created", "detailedProgress": { "progressNotes": [], "doneSteps": 0, "totalSteps": 4 }, "jobType": "SiteExportJob", "createdAt": 1514502992219, "updatedAt": 1514502992257, "statusMessageData": [], "jobTimeout": 43200, "statusMessage": "This job is queued." } } ``` ### Generate import mapping files Generates import mapping (.csv) files used to import a site from a site export (.zip) file. ``` POST /sites//import ``` #### Request path parameters `siteId` Required. The `siteId` is name of the site. See [Locating the siteId](#locating-the-siteid). #### Request query parameters `bucketName` Optional, unless `storageType` is set to `s3` (for Amazon S3 Storage). The name of the Amazon S3 storage bucket where the site export file is located. `continueOnIgnorableErrors` Optional. If set to `true`, site import will continue if ignorable errors are encountered. `exportFile` Required. Path to the export file. For export files stored on the local server, the default path must be under the directory defined by the `basefilepath.site_import.imports` configuration setting, which defaults to `/var/opt/tableau/tableau_server/data/tabsvc/files/siteimports`. `jobTimeoutSeconds` Optional. The timeout length in seconds. Default is 1800 seconds. `node` Optional. The node ID of the server node that is generating import mapping files. `scheduleMapperFile` Optional. The filename of the schedule mapper file (mapping-file.csv) that overrides normal schedule mapping by name. The directory where this file is found is set by the `basefilepath.site_import.overrides` configuration setting. `skipManualVerification` Optional, but must be set to `true` to use a remote storage option like Amazon S3. Skips verification of mapping files if set to `true`. `storageType` Optional. Determines the storage type used to store the previously created export file. If set to `filesystem` (the default value), the export file is stored on the local server. If set to `s3`, the export file is stored in Amazon S3 storage in the bucket defined by the `bucketName` parameter. #### Request body parameters `remoteStorageEncryptionInfo` Required only if `storageType` is set to `s3` because an Amazon S3 storage bucket is being used to store the export file. The `key` in the request is a the same base-64 encoded 256-bit AES symmetric key used to encrypt the export file when it was uploaded to S3 using the [`POST /sites//export`](#export-a-site) method. The same key is used to decrypt the file and generate mapping files. #### Request body example The following request body is only required if `storageType` is set to `s3` because an Amazon S3 storage bucket is being used to store the export file. ``` { "remoteStorageEncryptionInfo": { "key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" } } ``` #### Response status code 200 OK. #### Response body example ``` { "asyncJob": { "id": 12, "progress": -1, "args": "{\"node\":"localhost",\"siteUrl\":\"ImportTest"\",\"exportName\":\"DefaultExport.zip"\",\"skipVerification\":true }", "detailedProgress": { "progressNotes": [], "totalSteps": 0, "doneSteps": 0 }, "jobType": "SiteImportJob", "updatedAt": 1484263705085, "jobTimeout": 1800, "createdAt": 1484263705085, "statusMessageData": [] } } ``` ### Complete site import Imports a site using import mapping (.csv) files generated using the [`POST /sites//import`](#generate-import-mapping-files) method. ``` POST /sites//importverified ``` #### Request path parameters `siteId` Required. The `siteId` is name of the site. See [Locating the siteId](#locating-the-siteid). #### Request query parameters `jobTimeoutSeconds` Optional. The timeout length in seconds. Default is 1800 seconds. `node` Optional. The node ID of the server node that is performing the site export. `workingDirectory` Required. The path to a working directory that contains the import mapping files generated using the [`POST /sites//import`](#generate-import-mapping-files) method. This directory is located under the `/working` directory inside of the directory defined by the `basefilepath.site_import.imports` configuration setting, which defaults to `/var/opt/tableau/tableau_server/data/tabsvc/files/siteimports`. An example string for this parameter is `import 73943`. `storageType` Optional. Determines where the resulting export file will be stored. If set to `filesystem` (the default value), the export file is stored on the local server. If set to `s3`, the export file is stored in Amazon S3 storage in the bucket defined by the `bucketName` parameter. #### Response status code 200 OK. #### Response body example ``` { "asyncJob": { "id": 12, "progress": -1, "args": "{\"node\":"localhost",\"siteUrl\":\"ImportTest"\",\"workingDirectory\":\"import73943"\" }", "detailedProgress": { "progressNotes": [], "totalSteps": 0, "doneSteps": 0 }, "jobType": "SiteImportVerifiedJob", "updatedAt": 1484263705085, "jobTimeout": 1800, "createdAt": 1484263705085, "statusMessageData": [] } } ``` ### Unlock a site Unlock a site that was locked as the result of errors when importing or exporting a site. ``` POST /sites//unlock ``` #### Request path parameters `siteId` Required. The ID of the site. See [Locating the siteId](#locating-the-siteid). #### Query request parameters `jobTimeoutSeconds` Optional. The timeout length in seconds. Default is 1800 seconds. `desiredState` Optional. The state to set the site to when it is unlocked (`active` or `suspended`). Defaults to `active`. #### Response status code 200 OK. #### Response body example ``` { "asyncJob": { "id": 22, "args": "{\"desiredState\":\"active\",\"siteUrl\":\"MySite\"}", "progress": -1, "status": "Created", "detailedProgress": { "progressNotes": [], "doneSteps": 0, "totalSteps": 2 }, "statusMessageData": [], "updatedAt": 1504879269962, "statusMessage": "This job is queued.", "jobType": "SiteUnlockJob", "jobTimeout": 300, "createdAt": 1504879269951 } } ``` * * * ## Topology The TSM API topology endpoints are used to examine the server topology, which is the set of services running across all nodes of your Tableau Server deployment, and the binary version of each of those services, and to make updates to the topology. Like configurations, topologies are tracked across multiple versions. ### List topologies Get a list of the topology versions available. ``` GET /topologies ``` #### Response status code 200 OK #### Response body example ``` { "links": { "items": [{ "name": "0", "href": "/api/0.5/topologies/0" }, { "name": "1", "href": "/api/0.5/topologies/1" }, { "name": "2", "href": "/api/0.5/topologies/2" }, { "name": "3", "href": "/api/0.5/topologies/3" }, { "name": "requested", "href": "/api/0.5/topologies/requested" }, { "name": "pending", "href": "/api/0.5/topologies/pending" }] } } ``` ### Get the current topology version Gets the details of the current topology version. ``` GET /topologies/REQUESTED/version ``` #### Response status code 200 OK #### Response body example ``` { "version": "10" } ``` ### Get a topology version Gets the details of a specific topology version. ``` GET /topologies/ ``` #### Request path parameters `topology-version` Required. The version of the server topology to get details on. #### Response status code 200 OK #### Response body example ``` { "topologyVersion": { "nodes": { "node1": { "services": { "samlservice": { "instances": [ { "instanceId": "0", "requestedDeploymentState": "Disabled", "binaryVersion": "" } ] }, "searchserver": { "instances": [ { "instanceId": "0", "requestedDeploymentState": "Disabled", "binaryVersion": "" } ] }, "tabadmincontroller": { "instances": [ { "instanceId": "0", "requestedDeploymentState": "Enabled", "binaryVersion": "" } ] }, "tabsvc": { "instances": [ { "instanceId": "0", "requestedDeploymentState": "Enabled", "binaryVersion": "" } ] }, "pgsql": { "instances": [ { "instanceId": "0", "requestedDeploymentState": "Disabled", "binaryVersion": "" } ] }, "backuprestore": { "instances": [ { "instanceId": "0", "requestedDeploymentState": "Disabled", "binaryVersion": "" } ] }, "cacheserver": { "instances": [ { "instanceId": "0", "requestedDeploymentState": "Disabled", "binaryVersion": "" } ] }, "gateway": { "instances": [ { "instanceId": "0", "requestedDeploymentState": "Disabled", "binaryVersion": "" } ] }, "hyper": { "instances": [ { "instanceId": "0", "requestedDeploymentState": "Disabled", "binaryVersion": "" } ] }, "clustercontroller": { "instances": [ { "instanceId": "0", "requestedDeploymentState": "Disabled", "binaryVersion": "" } ] }, "vizportal": { "instances": [ { "instanceId": "0", "requestedDeploymentState": "Disabled", "binaryVersion": "" } ] }, "licenseservice": { "instances": [ { "instanceId": "0", "requestedDeploymentState": "Enabled", "binaryVersion": "" } ] }, "appzookeeper": { "instances": [ { "instanceId": "0", "requestedDeploymentState": "Enabled", "binaryVersion": "" } ] }, "vizqlserver": { "instances": [ { "instanceId": "0", "requestedDeploymentState": "Disabled", "binaryVersion": "" } ] }, "filestore": { "instances": [ { "instanceId": "0", "requestedDeploymentState": "Disabled", "binaryVersion": "" } ] }, "tabadminagent": { "instances": [ { "instanceId": "0", "requestedDeploymentState": "Enabled", "binaryVersion": "" } ] }, "siteimportexport": { "instances": [ { "instanceId": "0", "requestedDeploymentState": "Disabled", "binaryVersion": "" } ] }, "dataserver": { "instances": [ { "instanceId": "0", "requestedDeploymentState": "Disabled", "binaryVersion": "" } ] }, "databasemaintenance": { "instances": [ { "instanceId": "0", "requestedDeploymentState": "Disabled", "binaryVersion": "" } ] }, "backgrounder": { "instances": [ { "instanceId": "0", "requestedDeploymentState": "Disabled", "binaryVersion": "" } ] } }, "href": "/api/0.5/topologies/3/nodes/node1" } }, "href": "/api/0.5/topologies/3" } } ``` ### Validate a topology version against a configuration version Validates that a specified topology version conforms to the specified configuration version, and reports any violations (cases where the specified topology version does not conform to the specified configuration version). The response body returns the specified topology version, as well as a `violatedTopologyConstraints` JSON element that describes which, if any, violations occurred. ``` GET /topologies//violations ``` #### Request path parameters `topology-version` Required. The specified topology version number. #### Request query parameters `configurationVersion` Required. The specified configuration version number, obtained by calling [List configurations](#list-configurations). For example, you could use `?configurationVersion=9` for this query parameter. #### Response status code 200 OK #### Response body example ``` { "topologyVersion": { "nodes": { "node1": { "services": { "tabadmincontroller": { "instances": [ { "instanceId": "0", "requestedDeploymentState": "Enabled", "binaryVersion": "" } ] }, "tabsvc": { "instances": [ { "instanceId": "0", "requestedDeploymentState": "Enabled", "binaryVersion": "" } ] }, "licenseservice": { "instances": [ { "instanceId": "0", "requestedDeploymentState": "Enabled", "binaryVersion": "" } ] }, "pgsql": { "instances": [ { "instanceId": "0", "requestedDeploymentState": "Enabled", "binaryVersion": "" } ] }, "appzookeeper": { "instances": [ { "instanceId": "0", "requestedDeploymentState": "Enabled", "binaryVersion": "" } ] }, "backuprestore": { "instances": [ { "instanceId": "0", "requestedDeploymentState": "Disabled", "binaryVersion": "" } ] }, "tabadminagent": { "instances": [ { "instanceId": "0", "requestedDeploymentState": "Enabled", "binaryVersion": "" } ] }, "siteimportexport": { "instances": [ { "instanceId": "0", "requestedDeploymentState": "Disabled", "binaryVersion": "" } ] }, "clustercontroller": { "instances": [ { "instanceId": "0", "requestedDeploymentState": "Enabled", "binaryVersion": "" } ] }, "databasemaintenance": { "instances": [ { "instanceId": "0", "requestedDeploymentState": "Disabled", "binaryVersion": "" } ] } }, "href": "/api/0.5/topologies/2/nodes/node1" } }, "href": "/api/0.5/topologies/2" }, "violatedTopologyConstraints": { "items": [] } } ``` ### Get the topology of a single node Get details of the current topology for a single node of a server cluster. ``` GET /topologies//nodes/ ``` #### Request path parameters `topology-version` Required. The specified topology version number. `nodeId` The node ID. Note that node IDs are distinct from the computer address. For example, the node ID might be `node1`. #### Response status code 200 OK #### Response body example ``` { "topologyVersion": { "nodes": { "node1": { "services": { "samlservice": { "instances": [ { "instanceId": "0", "requestedDeploymentState": "Disabled", "binaryVersion": "" } ] }, "searchserver": { "instances": [ { "instanceId": "0", "requestedDeploymentState": "Disabled", "binaryVersion": "" } ] }, "tabadmincontroller": { "instances": [ { "instanceId": "0", "requestedDeploymentState": "Enabled", "binaryVersion": "" } ] }, "tabsvc": { "instances": [ { "instanceId": "0", "requestedDeploymentState": "Enabled", "binaryVersion": "" } ] }, "pgsql": { "instances": [ { "instanceId": "0", "requestedDeploymentState": "Enabled", "binaryVersion": "" } ] }, "backuprestore": { "instances": [ { "instanceId": "0", "requestedDeploymentState": "Disabled", "binaryVersion": "" } ] }, "cacheserver": { "instances": [ { "instanceId": "0", "requestedDeploymentState": "Disabled", "binaryVersion": "" } ] }, "gateway": { "instances": [ { "instanceId": "0", "requestedDeploymentState": "Disabled", "binaryVersion": "" } ] }, "hyper": { "instances": [ { "instanceId": "0", "requestedDeploymentState": "Disabled", "binaryVersion": "" } ] }, "clustercontroller": { "instances": [ { "instanceId": "0", "requestedDeploymentState": "Enabled", "binaryVersion": "" } ] }, "vizportal": { "instances": [ { "instanceId": "0", "requestedDeploymentState": "Disabled", "binaryVersion": "" } ] }, "licenseservice": { "instances": [ { "instanceId": "0", "requestedDeploymentState": "Enabled", "binaryVersion": "" } ] }, "appzookeeper": { "instances": [ { "instanceId": "0", "requestedDeploymentState": "Enabled", "binaryVersion": "" } ] }, "vizqlserver": { "instances": [ { "instanceId": "0", "requestedDeploymentState": "Disabled", "binaryVersion": "" } ] }, "filestore": { "instances": [ { "instanceId": "0", "requestedDeploymentState": "Disabled", "binaryVersion": "" } ] }, "tabadminagent": { "instances": [ { "instanceId": "0", "requestedDeploymentState": "Enabled", "binaryVersion": "" } ] }, "siteimportexport": { "instances": [ { "instanceId": "0", "requestedDeploymentState": "Disabled", "binaryVersion": "" } ] }, "dataserver": { "instances": [ { "instanceId": "0", "requestedDeploymentState": "Disabled", "binaryVersion": "" } ] }, "databasemaintenance": { "instances": [ { "instanceId": "0", "requestedDeploymentState": "Disabled", "binaryVersion": "" } ] }, "backgrounder": { "instances": [ { "instanceId": "0", "requestedDeploymentState": "Disabled", "binaryVersion": "" } ] } }, "href": "/api/0.5/topologies/10/nodes/node1" } }, "href": "/api/0.5/topologies/10" } } ``` ### Get the difference between two topology versions Gets the difference between one server topology version and another. ``` GET /topologies//diff/ ``` #### Request path parameters `from-topology-version` Required. The first topology version that is used for comparison. `to-topology-version` Required. The second topology version that is used for comparison. #### Response status code 200 OK #### Response body example ``` { "topologyVersion": { "nodes": { "node1": { "services": { "filestore": { "instances": [ { "instanceId": "0", "requestedDeploymentState": "Disabled", "binaryVersion": "" } ] }, "searchserver": { "instances": [ { "instanceId": "0", "requestedDeploymentState": "Disabled", "binaryVersion": "" } ] }, "dataserver": { "instances": [ { "instanceId": "0", "requestedDeploymentState": "Disabled", "binaryVersion": "" } ] }, "cacheserver": { "instances": [ { "instanceId": "0", "requestedDeploymentState": "Disabled", "binaryVersion": "" } ] }, "vizqlserver": { "instances": [ { "instanceId": "0", "requestedDeploymentState": "Disabled", "binaryVersion": "" } ] }, "vizportal": { "instances": [ { "instanceId": "0", "requestedDeploymentState": "Disabled", "binaryVersion": "" } ] }, "backgrounder": { "instances": [ { "instanceId": "0", "requestedDeploymentState": "Disabled", "binaryVersion": "" } ] }, "hyper": { "instances": [ { "instanceId": "0", "requestedDeploymentState": "Disabled", "binaryVersion": "" } ] }, "gateway": { "instances": [ { "instanceId": "0", "requestedDeploymentState": "Disabled", "binaryVersion": "" } ] }, "samlservice": { "instances": [ { "instanceId": "0", "requestedDeploymentState": "Disabled", "binaryVersion": "" } ] } } } }, "href": "/api/0.5/topologies/2/diff/9" } } ``` ### Delete a topology version Deletes the specified topology version. Subsequent topology version numbers will remain unchanged, resulting in gaps in the topology version sequence. For example, if you delete topology version 9, version 10 retains the same version number that it did previous to using this endpoint. This command takes effect immediately and does not restart Tableau Server. ``` DELETE /topologies/ ``` #### Request path parameters `topology-version` Required. The topology version to delete. #### Response status code 200 OK ### Update the pending topology Updates the pending topology for the nodes and services provided in the request body. Includes the option to delete the pending topology for any nodes that are not included in the request body. If successful, this endpoint returns the new topology. ``` PUT /topologies/PENDING ``` #### Request query parameters `removeMissingNodes` Optional. If set to `true`, any nodes not included in the request body have their pending topology deleted. #### Response status code 200 OK ### Update elements of the pending topology Updates the the elements of the pending topology that correspond to the JSON elements specified in the request body. The request body must contain the same elements and element structure as the response body provided by [`GET /topologies//diff/`](#get-the-difference-between-two-topology-versions). ``` PATCH /topologies/PENDING ``` #### Response status code 200 OK ### Update Tableau Server with the pending topology Updates Tableau Server with the pending topology. The response body provides the version number of the latest configuration version. ``` POST /topologies/PENDING/promote ``` #### Response status code 200 OK #### Response body example ``` { "version": "4" } ``` * * * ## Deployments Update the server configuration and server topology simultaneously, and check to see if changes will require a restart of the nodes in the server cluster. ### Update the configuration version and topology version Update both the server configuration and the server topology to the specified version numbers after validating that those versions exist. To check whether calling this endpoint will cause a restart of the server cluster that hosts Tableau Server, first send the request body to the [`POST /deployments/cluster-restart-needed`](#check-whether-an-update-to-the-configuration-version-and-topology-version-will-cause-a-cluster-restart) method. **Caution**: Calling this endpoint will cause an immediate restart of Tableau Server, resulting in downtime during that restart. ``` POST /deployments ``` #### Request body parameters `requestedTopologyVersion` Required. The version of the server topology to deploy. `requestedConfigurationVersion` Required. The version of the server configuration to deploy. #### Request body example ``` { "deployment":{ "requestedTopologyVersion":"2", "requestedConfigurationVersion":"2" } } ``` #### Response status code 200 OK #### Response body example ``` { "asyncJob": { "args": "{\"requestedConfigurationVersion\":\"2\",\"requestedTopologyVersion\":\"2\"}", "progress": 0, "id": 11, "status": "Running", "detailedProgress": { "progressNotes": [], "doneSteps": 0, "totalSteps": 20 }, "jobType": "DeploymentsJob", "createdAt": 1507055185005, "updatedAt": 1507055185017, "statusMessageData": [], "jobTimeout": 1200, "worker": "node1", "statusMessage": "This job is currently running." } } ``` ### Check whether an update to the configuration version and topology version will cause a cluster restart Check whether calling the [`POST /deployments`](#update-the-configuration-version-and-topology-version) method with a given request body will cause a restart of the server cluster that hosts Tableau Server. The response body will contain `true` if a restart of the server cluster is needed, or `false` if it is not needed. ``` POST /deployments/cluster-restart-needed ``` #### Request body parameters `requestedTopologyVersion` Required. The version of the server topology to deploy. `requestedConfigurationVersion` Required. The version of the server configuration to deploy. #### Request body example ``` { "deployment":{ "requestedTopologyVersion":"2", "requestedConfigurationVersion":"2" } } ``` #### Response status code 200 OK #### Response body example ``` { "clusterRestartNeeded": { "clusterRestartNeeded": true } } ``` * * * ## Ports Get and set ports assigned to Tableau Server services. These methods allow you to manage port assignments across all nodes, or scoped to specific nodes, services and service instances. ### Get ports for all nodes Get port assignments for all Tableau Server services. ``` GET /ports ``` #### Request query parameters `jobTimeoutSeconds` Optional. The timout length in seconds. #### Response status code 200 OK #### Response body example ``` { "clusterPorts": { "nodes": [ { "services": [ { "serviceName": "filestore", "instances": [ { "instanceId": 0, "ports": [ { "port": 8404, "portType": "primary" }, { "port": 8308, "portType": "status" } ] } ] }, { "serviceName": "siteimportexport", "instances": [ { "instanceId": 0, "ports": [ { "port": 8500, "portType": "primary" } ] } ] }, { "serviceName": "databasemaintenance", "instances": [ { "instanceId": 0, "ports": [ { "port": 8077, "portType": "primary" } ] } ] }, { "serviceName": "dataserver", "instances": [ { "instanceId": 0, "ports": [ { "port": 8572, "portType": "primary" }, { "port": 8045, "portType": "debug" }, { "port": 8781, "portType": "jmx" }, { "port": 8501, "portType": "jmx.rmi" } ] } ] }, { "serviceName": "cacheserver", "instances": [ { "instanceId": 0, "ports": [ { "port": 8614, "portType": "primary" } ] } ] }, { "serviceName": "tabadmincontroller", "instances": [ { "instanceId": 0, "ports": [ { "port": 8850, "portType": "primary" } ] } ] }, { "serviceName": "vizqlserver", "instances": [ { "instanceId": 0, "ports": [ { "port": 8549, "portType": "primary" }, { "port": 8178, "portType": "debug" }, { "port": 8249, "portType": "jmx" }, { "port": 8668, "portType": "jmx.rmi" } ] } ] }, { "serviceName": "backgrounder", "instances": [ { "instanceId": 0, "ports": [ { "port": 8940, "portType": "primary" }, { "port": 8093, "portType": "debug" }, { "port": 8537, "portType": "jmx" }, { "port": 8851, "portType": "jmx.rmi" } ] } ] }, { "serviceName": "appzookeeper", "instances": [ { "instanceId": 0, "ports": [ { "port": 8640, "portType": "client" }, { "port": 8324, "portType": "peer" }, { "port": 8706, "portType": "leader" } ] } ] }, { "serviceName": "searchserver", "instances": [ { "instanceId": 0, "ports": [ { "port": 8217, "portType": "primary" }, { "port": 8586, "portType": "debug" }, { "port": 8624, "portType": "jmx" }, { "port": 8316, "portType": "jmx.rmi" }, { "port": 8206, "portType": "startup" } ] } ] }, { "serviceName": "clustercontroller", "instances": [ { "instanceId": 0, "ports": [ { "port": 8277, "portType": "status" }, { "port": 8977, "portType": "storage" } ] } ] }, { "serviceName": "vizportal", "instances": [ { "instanceId": 0, "ports": [ { "port": 8269, "portType": "primary" }, { "port": 8659, "portType": "debug" }, { "port": 8485, "portType": "jmx" }, { "port": 8797, "portType": "jmx.rmi" }, { "port": 8146, "portType": "authentication" }, { "port": 8414, "portType": "authorization" }, { "port": 8301, "portType": "maintenance" } ] } ] }, { "serviceName": "backuprestore", "instances": [ { "instanceId": 0, "ports": [ { "port": 8798, "portType": "primary" } ] } ] }, { "serviceName": "gateway", "instances": [ { "instanceId": 0, "ports": [ { "port": 80, "portType": "primary" } ] } ] }, { "serviceName": "hyper", "instances": [ { "instanceId": 0, "ports": [ { "port": 8362, "portType": "primary" }, { "port": 8859, "portType": "connection" } ] } ] }, { "serviceName": "samlservice", "instances": [ { "instanceId": 0, "ports": [ { "port": 8866, "portType": "primary" } ] } ] }, { "serviceName": "tabadminagent", "instances": [ { "instanceId": 0, "ports": [ { "port": 8388, "portType": "filetransfer" } ] } ] } ], "nodeId": "node1" } ] } } ``` ### Set ports for all nodes Set port assignments for Tableau Server services. The request body must be a modified version of the response body provided by [`GET /ports`](#get-ports-for-all-nodes). **Caution**: Calling this endpoint causes an immediate restart of Tableau Server, resulting in downtime during that restart. ``` PUT /ports ``` #### Request query parameters `jobTimeoutSeconds` Optional. The timout length in seconds. #### Response status code 200 OK #### Response body example ``` { "asyncJob": { "progress": 0, "id": 12, "status": "Running", "detailedProgress": { "progressNotes": [ { "step": "ConfigureServices", "messageData": [], "timestamp": 1507057436496, "message": "Reconfiguring services.", "status": "Running" } ], "doneSteps": 0, "totalSteps": 2 }, "jobType": "ReconfigureJob", "createdAt": 1507057436474, "updatedAt": 1507057436496, "statusMessageData": [], "jobTimeout": 420, "worker": "node1", "statusMessage": "This job is currently running." } } ``` ### Get ports for a node Get port assignments for all Tableau Server services on a single server node. ``` GET /ports/nodes/ ``` #### Request path parameters `nodeId` The node that you want to get port assignments from. #### Response status code 200 OK #### Response body example ``` { "nodePorts": { "services": [ { "serviceName": "filestore", "instances": [ { "instanceId": 0, "ports": [ { "port": 8422, "portType": "primary" }, { "port": 8668, "portType": "status" } ] } ] }, { "serviceName": "siteimportexport", "instances": [ { "instanceId": 0, "ports": [ { "port": 8956, "portType": "primary" } ] } ] }, { "serviceName": "databasemaintenance", "instances": [ { "instanceId": 0, "ports": [ { "port": 8907, "portType": "primary" } ] } ] }, { "serviceName": "cacheserver", "instances": [ { "instanceId": 0, "ports": [ { "port": 8287, "portType": "primary" } ] } ] }, { "serviceName": "dataserver", "instances": [ { "instanceId": 0, "ports": [ { "port": 8354, "portType": "primary" }, { "port": 8750, "portType": "debug" }, { "port": 8577, "portType": "jmx" }, { "port": 8904, "portType": "jmx.rmi" } ] } ] }, { "serviceName": "tabadmincontroller", "instances": [ { "instanceId": 0, "ports": [ { "port": 8850, "portType": "primary" } ] } ] }, { "serviceName": "vizqlserver", "instances": [ { "instanceId": 0, "ports": [ { "port": 8731, "portType": "primary" }, { "port": 8541, "portType": "debug" }, { "port": 8691, "portType": "jmx" }, { "port": 8172, "portType": "jmx.rmi" } ] } ] }, { "serviceName": "backgrounder", "instances": [ { "instanceId": 0, "ports": [ { "port": 8624, "portType": "primary" }, { "port": 8263, "portType": "debug" }, { "port": 8900, "portType": "jmx" }, { "port": 8088, "portType": "jmx.rmi" }, { "port": 8827, "portType": "recommendations.trainer" } ] } ] }, { "serviceName": "appzookeeper", "instances": [ { "instanceId": 0, "ports": [ { "port": 8332, "portType": "client" }, { "port": 8797, "portType": "leader" }, { "port": 8863, "portType": "peer" } ] } ] }, { "serviceName": "searchserver", "instances": [ { "instanceId": 0, "ports": [ { "port": 8501, "portType": "primary" }, { "port": 8244, "portType": "debug" }, { "port": 8997, "portType": "jmx" }, { "port": 8396, "portType": "jmx.rmi" }, { "port": 8778, "portType": "startup" } ] } ] }, { "serviceName": "clustercontroller", "instances": [ { "instanceId": 0, "ports": [ { "port": 8167, "portType": "status" }, { "port": 8028, "portType": "storage" } ] } ] }, { "serviceName": "vizportal", "instances": [ { "instanceId": 0, "ports": [ { "port": 8402, "portType": "primary" }, { "port": 8141, "portType": "debug" }, { "port": 8706, "portType": "jmx" }, { "port": 8661, "portType": "jmx.rmi" }, { "port": 8774, "portType": "authentication" }, { "port": 8397, "portType": "authorization" }, { "port": 8667, "portType": "maintenance" }, { "port": 8639, "portType": "publishing" }, { "port": 8465, "portType": "recommendations" } ] } ] }, { "serviceName": "backuprestore", "instances": [ { "instanceId": 0, "ports": [ { "port": 8500, "portType": "primary" } ] } ] }, { "serviceName": "gateway", "instances": [ { "instanceId": 0, "ports": [ { "port": 80, "portType": "primary" } ] } ] }, { "serviceName": "samlservice", "instances": [ { "instanceId": 0, "ports": [ { "port": 8166, "portType": "primary" } ] } ] }, { "serviceName": "hyper", "instances": [ { "instanceId": 0, "ports": [ { "port": 8001, "portType": "primary" }, { "port": 8210, "portType": "connection" } ] } ] }, { "serviceName": "tabadminagent", "instances": [ { "instanceId": 0, "ports": [ { "port": 8949, "portType": "filetransfer" } ] } ] } ], "nodeId": "node1" } } ``` ### Set ports for a node Set port assignments for Tableau Server services on a node. The request body must be a modified version of the response body provided by [`GET /ports/nodes/`](#get-ports-for-a-node). **Caution**: Calling this endpoint causes an immediate restart of Tableau Server, resulting in downtime during that restart. ``` PUT /ports/nodes/ ``` #### Request path parameters `nodeId` The node that you want to set port assignments for. #### Request query parameters `jobTimeoutSeconds` Optional. Specifies the number of seconds before the job times out. #### Response status code 200 OK #### Response body example ``` { "asyncJob": { "progress": -1, "id": 11, "status": "Created", "detailedProgress": { "progressNotes": [], "doneSteps": 0, "totalSteps": 2 }, "jobType": "ReconfigureJob", "createdAt": 1514583948170, "updatedAt": 1514583948178, "statusMessageData": [], "jobTimeout": 420, "statusMessage": "This job is queued." } } ``` ### Get ports for a service on a node Get port assignments for a Tableau Server service on a node. ``` GET /ports/nodes//services/ ``` #### Request path parameters `nodeId` The node that you want to get port assignments from. `serviceName` The name of the service that you want to get port assignments from. #### Response status code 200 OK #### Response body example ``` { "servicePorts": { "serviceName": "filestore", "instances": [ { "instanceId": 0, "ports": [ { "port": 8422, "portType": "primary" }, { "port": 8668, "portType": "status" } ] } ] } } ``` ### Set ports for a service on a node Set port assignments for a Tableau Server service on a node. The request body must be a modified version of the response body provided by [`GET /ports/nodes//services/`](#get-ports-for-a-service-on-a-node). **Caution**: Calling this endpoint causes an immediate restart of Tableau Server, resulting in downtime during that restart. ``` SET /ports/nodes//services/ ``` #### Request path parameters `nodeId` The node that you want to set port assignments form. `serviceName` The name of the service that you want to set port assignments for. #### Response status code 200 OK #### Response body example ``` { "asyncJob": { "progress": 0, "id": 15, "status": "Running", "detailedProgress": { "progressNotes": [], "doneSteps": 0, "totalSteps": 2 }, "jobType": "ReconfigureJob", "createdAt": 1514587134936, "updatedAt": 1514587134997, "statusMessageData": [], "jobTimeout": 420, "worker": "node1", "statusMessage": "This job is currently running." } } ``` ### Get ports for a service instance on a node Get port assignments for a Tableau Server service instance on a node. ``` GET /ports/nodes//services// ``` #### Request path parameters `nodeId` The node that you want to get port assignments from. `serviceName` The name of the service that you want to get port assignments from. `instanceId` The ID number of the service instance. #### Response status code 200 OK #### Response body example ``` { "instancePorts": { "instanceId": 0, "ports": [ { "port": 8624, "portType": "primary" }, { "port": 8263, "portType": "debug" }, { "port": 8900, "portType": "jmx" }, { "port": 8088, "portType": "jmx.rmi" }, { "port": 8827, "portType": "recommendations.trainer" } ] } } ``` ### Set ports for a service instance on a node Set port assignments for a Tableau Server service instance on a node. The request body must be a modified version of the response body provided by [`GET /ports/nodes//services//`](#get-ports-for-a-service-instance-on-a-node). **Caution**: Calling this endpoint causes an immediate restart of Tableau Server, resulting in downtime during that restart. ``` GET /ports/nodes//services// ``` #### Request path parameters `nodeId` The node that you want to set port assignments from. `serviceName` The name of the service that you want to set port assignments from. `instanceId` The ID number of the service instance. #### Response status code 200 OK #### Response body example ``` { "asyncJob": { "progress": -1, "id": 16, "status": "Created", "detailedProgress": { "progressNotes": [], "doneSteps": 0, "totalSteps": 0 }, "jobType": "ReconfigureJob", "createdAt": 1514587668481, "updatedAt": 1514587668481, "statusMessageData": [], "jobTimeout": 420, "statusMessage": "This job is queued." } } ``` * * * ## Security Configure Tableau Server security. These methods create or delete secure socket layer (SSL) configuration settings for external (gateway) SSL and recreate the security tokens that Tableau Server uses internally. To learn more about managing SSL in Tableau Server, see [tsm security](http://help.tableau.com/v10.5/server-linux/en-us/cli_security_tsm.htm?Highlight=certfile#external-ssl-enable). ### Configure and enable external SSL Configure Tableau Server’s external (gateway) SSL configuration settings to encrypt traffic between external clients and Tableau Server. ``` POST /security/gateway-external-ssl ``` #### Request body parameters The request body must use the `multipart form-data` type. `certFile` Required. A valid PEM-encoded x509 certificate with the `.crt` file extension. `keyFile` Required. A valid RSA or DSA private key file, with the `.key` file extension. `chainFile` Optional, but required to support deployments that use Tableau Mobile and Tableau Desktop on the Mac. Some certificate providers issue two certificates for Apache web server. The second certificate is a chain file, which is a concatenation of all the certificates that form the certificate chain for the server certificate. All certificates in the chain file must be x509 PEM-encoded and the file must have a `.crt` extension. `passphrase` Optional. Passphrase for the certificate file. The passphrase you enter will be encrypted while at rest. `protocols` Optional. List the Transport Layer Security (TLS) protocol versions you want to allow or disallow. TLS is an improved version of SSL. Tableau Server uses TLS to authenticate and encrypt connections. Accepted values include protocol versions supported by Apache. To disallow a protocol, prepend the protocol version with a minus (-) character. The default setting is `"all, -SSLv2, -SSLv3"` This default explicitly does not allow clients to use SSL v2 or SSL v3 protocols to connect to Tableau Server. However, we recommend that you also disallow TLS v1 and TLS v1.1. Before you deny a specific version of TLS, verify that the browsers from which your users connect to Tableau Server support TLS v1.2. You might need to preserve support for TLS v1.1 until your users update their browsers. If you do not need to support TLS v1 or v1.1, set the following value for this parameter to allow TLS v1.2 (using the value all), and explicitly deny SSL v2, SSL v3, TLS v1, and TLS v1.1: `"all -SSLv2 -SSLv3 -TLSv1 -TLSv1.1"` #### Response status code 204 No Content TODO complete ### Remove SSL configuration and disable external SSL Remove Tableau Server’s existing external (gateway) SSL configuration settings and stop encrypting traffic between external clients and Tableau Server. ``` DELETE /security/gateway-external-ssl ``` #### Response status code 204 No Content ### Recreate internal security tokens Recreate the tokens used by Tableau Server to access the repository, and the certificates used to validate internal SSL connections between Tableau Server components and the repository. **Caution**: Calling this endpoint causes an immediate restart of Tableau Server, resulting in downtime during that restart. ``` POST /security/regenerate-internal-tokens ``` #### Response status code 200 OK #### Response body example ``` { "asyncJob": { "progress": 0, "id": 13, "status": "Running", "detailedProgress": { "progressNotes": [], "doneSteps": 0, "totalSteps": 24 }, "jobType": "RegenerateInternalTokens", "createdAt": 1507058104158, "updatedAt": 1507058104273, "statusMessageData": [], "jobTimeout": 1500, "worker": "node1", "statusMessage": "This job is currently running." } } ``` * * * ## Log Files Tableau Server creates archives that contain the complete set of current Tableau Server log files. You can use the `/ziplogs` methods to create a .zip file archive, which is stored on your server. ### Create log file archive Create a log file archive (logs.zip). The file is written to the directory defined in the TSM `basefilepath.log_archive` variable. By default, this directory is `/var/opt/tableau/tableau_server/data/tabsvc/files/log-archives/`. For more information about file paths and how to change them, see [tsm File Paths](http://help.tableau.com/current/server-linux/en-us/cli_default_filepaths_tsm.htm). ``` POST /ziplogs ``` #### Request query parameters `description` Optional. A description of the log file archive. `jobTimeoutSeconds` Optional. Specifies the number of seconds before the job times out. `minimumDate` Optional. Earliest date of files to be included. If not specified, a maximum of two days of data are included. The expected date format is `mm/dd/yyyy`. `overwrite` Optional. Overwrites the an existing file with the same filename, if it exists. `withNetstatInfo` Optional. Include netstat information. `withPostgresqlData` Optional. Include the PostgreSQL data folder if Tableau Server is stopped or PostgreSQL dump files if Tableau Server is running. `withLatestDump` Optional. Include latest dumps. `writepath` Required. The name for the ziplogs file. Ziplogs files are placed in the data directory. By default, you can find ziplogs files in the following location: ``` /var/opt/tableau/tableau_server/data/tabsvc/files/log-archives ``` #### Response status code 200 OK #### Response body example ``` { "asyncJob": { "args": "{\"withNetstatInfo\":false,\"withPostgresqlData\":false,\"withLatestDump\":false,\"minimumDate\":[2017,6,7],\"node\":\"node1\"}", "progress": 0, "id": 14, "status": "Running", "detailedProgress": { "progressNotes": [], "doneSteps": 0, "totalSteps": 0 }, "jobType": "ZiplogsJob", "createdAt": 1497062264656, "updatedAt": 1497062264669, "statusMessageData": [], "jobTimeout": 1800, "worker": "node1", "statusMessage": "This job is currently running." } } ``` ### Create log file archive with a specified filename Create a log file archive with a specified filename. The file is written to the directory defined in the TSM `basefilepath.log_archive` variable. By default, this directory is `/var/opt/tableau/tableau_server/data/tabsvc/files/log-archives/` For more information about file paths and how to change them, see [tsm File Paths](http://help.tableau.com/current/server-linux/en-us/cli_default_filepaths_tsm.htm). ``` POST /ziplogsFixedFile ``` #### Request query parameters `description` Optional. A description of the log file archive. `jobTimeoutSeconds` Optional. Specifies the number of seconds before the job times out. `minimumDate` Optional. The earliest date of files to be included. If not specified, a maximum of two days of data are included. The expected date format is `mm/dd/yyyy`. `withNetstatInfo` Optional. Include netstat information. `withPostgresqlData` Optional. Include the PostgreSQL data folder if Tableau Server is stopped or PostgreSQL dump files if Tableau Server is running. `withLatestDump` Optional. Include latest dumps. `writepath` Required. The name for the ziplogs file. Ziplogs files are placed in the data directory. By default, you can find ziplogs files in the following location: ``` /var/opt/tableau/tableau_server/data/tabsvc/files/log-archives ``` #### Response status code 200 OK #### Response body example ``` { "asyncJob": { "args": "{\"withNetstatInfo\":false,\"withPostgresqlData\":false,\"withLatestDump\":false,\"minimumDate\":[2017,6,7],\"node\":\"node1\"}", "progress": 0, "id": 14, "status": "Running", "detailedProgress": { "progressNotes": [], "doneSteps": 0, "totalSteps": 0 }, "jobType": "ZiplogsJob", "createdAt": 1497062264656, "updatedAt": 1497062264669, "statusMessageData": [], "jobTimeout": 1800, "worker": "node1", "statusMessage": "This job is currently running." } } ``` ### Get log file archive list Get a list of log file archives (or “snapshots”), along with details including when the log file was created (milliseconds since January 1st, 1970), the size of the archive in bytes, and an ID number that is required for the [`POST \sendlogs`](#send-log-file-archive-to-tableau), [`GET \snapshots\`](#get-log-file-archive), and [`DELETE \snapshots\`](#delete-log-file-archive) methods. ``` GET /snapshots ``` #### Response status code 200 OK #### Response body example ``` { "logSnapshotInfo": { "snapshots": [ { "createdDate": 1513905215873, "archiveSize": 5546728, "ziplogsStatus": "Succeeded", "sendlogsStatus": "Succeeded", "id": 1, "node": "node1", "range": 72 }, { "createdDate": 1513970549847, "archiveSize": 20553477, "ziplogsStatus": "Succeeded", "id": 2, "node": "node1", "range": 72 }, { "createdDate": 1513971159342, "archiveSize": 21228741, "ziplogsStatus": "Succeeded", "id": 3, "node": "node1", "range": 72 } ] } } ``` ### Get log file archive Get a log file archive, shown as text in the response body. ``` GET /snapshots/ ``` #### Request path parameters `snapshotId` The ID of the log file archive, provided in the `id` field when you call [`GET /snapshots`](#get-log-file-archive-list). #### Response status code 200 OK #### Response body example The response body shows the contents of the log file archive, rendered as plan text. Because this response body is thousands of lines, it is not provided here. ### Delete log file archive Delete a log file archive. ``` DELETE /snapshots/ ``` #### Request path parameters `snapshotId` The ID of the log file archive, provided in the `id` field when you call [`GET /snapshots`](#get-log-file-archive-list). #### Response status code 204 No Content ### Send log file archive to Tableau Upload the specified log file archive to Tableau and associate it with a support case and your email address. ``` POST \sendlogs ``` #### Request query parameters `caseNumber` Required. The case number provided by Tableau Support. `email` Required. The email address that Tableau Support will use as contact information to follow-up with you `jobTimeoutSeconds` Optional. Specifies the number of seconds before the job times out. `logPackagePath` Optional; but you must provide either `logPackagePath` or `snapshotId` in this request. The full path, including the filename, of the log file archive. `snapshotId` Optional; but you must provide either `logPackagePath` or `snapshotId` in this request. The ID of the log file archive, provided in the `id` field when you call [`GET /snapshots`](#get-log-file-archive-list). #### Response status code 204 No Content