Flow Methods
Using the flow methods of the Tableau Server REST API you can do the operations listed in the following categories:
Flows (sets of data preparation steps for a site)
- Get a list of flows for a site or the users and details of a specific flow
- Get a list of flow runs for a site
- Run a specific flow with all or a specified set of output steps
- Run a specific flow with parameter values
- Cancel a specific flow run
- Publish, update, delete and download a flow
Flow Tasks (scheduled or manually initiated tasks that perform flows for a site)
- Get a list of flow tasks for a site and details of a specific flow task
- Run a flow task
- Add a flow task to a schedule
- Add a flow task to a schedule with parameter values
- Get a list of linked tasks for a site and details of a specific linked task
- Run a linked task
Flow Connections (connections to data sources of a flow)
- Get and update the connection information for a flow task
Flow Permissions (user permissions to initiate a flow)
- List, grant, and remove granular permissions of a user to a flow
This functionality relates to the UI elements and concepts described at: Tableau Prep Conductor(Link opens in a new window).
Add Flow Permissions
Adds permissions to the specified flow for a Tableau Server user or group. You can specify multiple sets of permissions using one call.
URI
PUT /api/api-version/sites/site-id/flows/flow-id/permissions
Parameter Values
api-version | The version of the API to use, such as 3.24 . For more information, see REST API and Resource Versions. |
site-id | The ID of the site that contains the flow. |
datasource-id | The ID of the flow. |
Request Body
<tsRequest>
<permissions>
<flow id="flow-id" />
<granteeCapabilities>
<user id="user-id" />
<capabilities>
<capability name="capability-name" mode="capability-mode" />
... additional capabilities ...
</capabilities>
</granteeCapabilities>
<granteeCapabilities>
<group id="group-id" />
<capabilities>
<capability name="capability-name" mode="capability-mode" />
... additional capabilities ...
</capabilities>
</granteeCapabilities>
... additional grantee capability sets ...
</permissions>
</tsRequest>
Attribute Values
flow-id | The flow-id value for the flow you want to add permissions to. |
user-id | The ID (not name) of the user to add permissions for. |
group-id | The ID (not name) of the group to add permissions for. |
capability-name |
The capability to assign. If any capability has already been granted or denied for a specified user or group, that capability is ignored. Valid capabilities for a flow are:
For more information, see Permissions. |
Permissions
Tableau Server users who are not server administrators or site administrators can call this method only if they have permission to set permissions on the flow (either explicitly or implicitly).
Response Code
200
Response Body
<tsResponse>
<permissions>
<flow id="8359f0c5-4b98-4ca4-a7e5-38e4261e88a2" name="Flow1">
<owner id="8f735728-7484-40d1-89d1-41f09824536b"/>
</flow>
<granteeCapabilities>
<group id="9de5cc1a-5bb8-4c8e-b2cd-b54e736a7b9f"/>
<capabilities>
<capability name="Read" mode="Allow"/>
<capability name="Write" mode="Allow"/>
<capability name="Delete" mode="Deny"/>
</capabilities>
</granteeCapabilities>
<granteeCapabilities>
<user id="1f2345678-1234-12d1-12d1-11f234567b"/>
<capabilities>
<capability name="Delete" mode="Allow"/>
</capabilities>
</granteeCapabilities>
</permissions>
</tsResponse>
Version
Version 3.3 and later. For more information, see REST API and Resource Versions.
Errors
HTTP status | error Code |
Condition | Details |
---|---|---|---|
400 | 400000 | Bad request | The content of the request body is missing or incomplete, or contains malformed XML. |
400 | 400009 | Invalid capability | The capability in the URI is invalid for a flow. Valid capabilities for a flow are ChangeHierarchy, ChangePermissions, Delete, Execute, ExportXml (Download), Read (view), and Write. |
403 | 403004 | Permissions setting forbidden | A non-administrator user called this method but doesn't have permission to set permissions on the flow. |
404 | 404000 | Site not found | The site ID in the URI doesn't correspond to an existing site. |
404 | 404002 | User not found | A user ID in the request body doesn't correspond to an existing user. |
404 | 404027 | Flow not found | The flow ID in the URI doesn't correspond to an existing flow. |
404 | 404012 | Group not found | A group ID in the request body doesn't correspond to an existing group. |
404 | 404013 | Capability not found | The specified capability doesn't correspond to a defined capability. This can apply to either an invalid capability name or a capability other than Allow or Deny for any mode value. |
For more information, see Handling Errors.
Add Flow Task to Server Schedule
The Add Flow Task to Schedule method is renamed and retired for Tableau Cloud in API 3.22 (Tableau Cloud March 2024). It will remain available for Tableau Server only. For Tableau Cloud in March 2024, this method will be replaced with Create Cloud Flow Task method.
Adds a task to run a flow to an existing schedule.
Note: This method is unavailable if you do not have a Data Management license or Tableau Prep Conductor is disabled for your site.
URI
PUT /api/api-version/sites/site-id/schedules/schedule-id/flows
Parameter Values
api-version | The version of the API to use, such as 3.24 . For more information, see REST API and Resource Versions. |
site-id | The ID of the site that contains the flow. |
schedule-id | The ID of the schedule that you are associating with the flow. The schedule that you are adding to must have Flow as the schedule type. |
Request Body
<tsRequest>
<task>
<flowRun>
<flow id="flow-id"/>
<flowRunSpec>
<flowParameterSpecs>
<flowParameterSpec
parameterId="parameter-id"
overrideValue= "overrideValue"/>
<flowParameterSpecs>
<flowRunSpec>
</flowRun>
</task>
</tsRequest>
Attribute Values
flow-id |
The ID of the flow to add to the schedule. This will include all the output steps in the flow and any output steps created in the future. |
parameter-id |
The ID of the flow parameter. Use the Flow Methods method to get the flow parameter ID. A parameter is a global placeholder value such as a number, text value, or boolean value that can replace a constant value in a flow. Note: Parameters are optional and only relevant for flows that contain parameters and the parameter setting is enabled. For more information, see Run flows with parameters. |
overrideValue |
The run-time value for the flow parameter. You must specify this if the parameter is required. Use the Flow Methods method to see if the parameter is required and to get a list of allowed values if the parameter is expecting a value from an enumerated list. Note: Parameters are options and only relevant for flows that contains parameters and the parameter setting is enabled. For more information, see Run flows with parameters. |
Permissions
Tableau Server users who are not server administrators or site administrators can only add a flow to a schedule if they own the flow, or are the project leader for the project that contains the workbook.
Response Code
200
Version
Version 3.3 and later. For more information, see REST API and Resource Versions.
Errors
HTTP status | error Code |
Condition | Details |
---|---|---|---|
400 | 400000 | Bad request | The content of the request body is missing or incomplete, or contains malformed XML. |
400 | 400148 | Invalid parameter override value | The run-time value provided for the flow parameter is invalid. |
400 | 400149 | Missing run-time parameter value. | The run-time value for a required flow parameters was not provided. |
401 | 401002 | Unauthorized Access | The authentication token provided in the request header was invalid or has expired. |
403 | 403098 | Update Forbidden | A non-administrator user called this method, but the caller doesn't have sufficient permissions. |
404 | 404000 | Site not found | The site ID in the URI is unknown. |
404 | 404043 | Flow parameter not found | The flow parameter information was not provided. |
404 | 404002 | User not found | A user ID in the request body doesn't correspond to an existing user. |
404 | 404027 | Flow not found | The flow ID in the URI doesn't correspond to an existing flow. |
405 | 405000 | Invalid request method | Request type was not PUT. |
For more information, see Handling Errors.
Example
curl "http://MY-SERVER/api/3.24/sites/1edc53ac-e247-4870-9fd3-6fad0ce5f84d/schedules/9a4ebbab-9ec8-487a-9b48-47fa81d6077a/flows" -X PUT -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" –d @add-to-schedule.xml"
Content of add-to-schedule.xml:
The <flowRunSpec> in the request body is optional and only required in the following scenarios:
- The flow has parameters and the parameter is marked as required to run the flow.
- The flow has parameters but not marked as required. However, you want to specify a different value than the configured default.
<tsRequest>
<task>
<flowRun>
<flow id="5ab9cd53-e17f-45gh-804i-4914jk39r29z"/>
<flowRunSpec>
<flowParameterSpecs>
<flowParameterSpec>
parameterId="a2fb691b-90fa-4b6e-850e-f16c5afc1f89"
overrideValue= "2"/>
<flowParameterSpecs>
<flowRunSpec>
</flowRun>
</task>
</tsRequest
Example response:
<tsResponse version-and-namespace-settings>
<task>
<flowRun id="8a78c68e-37ad-4b21-80fc-e67e2ab55279" priority="50" consecutiveFailedCount="0" type="RunFlowTask">
<schedule id="99e8841e-8527-4d09-89b8-71d9872634df" name="demo" state="Active" priority="50" createdAt="2021-12-09T19:21:09Z" updatedAt="2022-01-19T23:06:56Z" type="Flow" frequency="Hourly" nextRunAt="2022-01-20T00:00:00Z"/>
<flow id="09942c88-99d5-4669-aa62-07560fc4b201" name="CoffeeChain"/>
<flowParametersRuns>
<parameterRuns parameterId="a2fb691b-90fa-4b6e-850e-f16c5afc1f89" name="param 2 required" description=testparameter2" overrideValue = "2"/>
<flowParametersRuns>
</flowRun>
</task>
</tsResponse>
Cancel Flow Run
Cancels a flow run that is in progress.
URI
PUT /api/api-version/sites/site-id/flows/runs/flow-run-id
Parameter Values
api-version | The version of the API to use, such as 3.24 . For more information, see REST API and Resource Versions. |
site-id | The ID of the site that contains the flow. |
flow-run-id | The ID of the flow run. |
Request Body
None
Response Code
200
Response Body
None
Version
Version 3.10 and later. For more information, see REST API and Resource Versions.
Errors
HTTP status | error Code |
Condition | Details |
---|---|---|---|
403 | 403135 | Flow run already complete | The flow run is already complete so it could not be canceled. |
403 | 403137 | User does not have permissions to cancel flow run | In addition to server administrators and site administrators, users can cancel a flow run if they initiated the flow run or created the flow run scheduled task and have "Run Flow Now" permissions for the flow. |
404 | 404000 | Site not found | The site ID or URL namespace in the URI doesn't correspond to an existing site. |
404 | 404036 | Flow run not found | The flow run ID in the URI doesn't correspond to an existing flow run. |
405 | 405000 | Invalid request method | Request type was not PUT. |
For more information, see Handling Errors.
Create Cloud Flow Task
Creates a flow task on Tableau Cloud, and set its schedule.
Note: This method is unavailable if you do not have a Data Management license or Tableau Prep Conductor is disabled for your site.
Version: Available in API 3.22 (Tableau Cloud April 2024) and later. Not available for Tableau Server. Version Overview(Link opens in a new window)
License: Requires Tableau Data Management(Link opens in a new window).
Permissions: A user can create a cloud flow task if you are a site or server administrator, or they own the flow, or are the project leader for the project that contains the workbook. Permissions Overview(Link opens in a new window)
JWT Access Scope: Not available. Access Scopes Overview: Cloud(Link opens in a new window)
URI
POST /api/api-version/sites/site-luid/tasks/flows
URI Parameter Values
api-version | The version of the API to use, such as 3.24 . For more information, see REST API and Resource Versions.
|
site-luid | The LUID for the site. |
Request Body
<tsRequest>
<task>
<flowRun>
<flow id="dd3cd2e7-2ede-49c6-945f-e7b2a2f25541"/>
</flowRun>
</task>
<schedule frequency="Daily">
<frequencyDetails start="12:30:00" end="23:30:00">
<intervals>
<interval hours="4"/>
<interval weekDay="Monday"/>
<interval weekDay="Wednesday"/>
</intervals>
</frequencyDetails>
</schedule>
</tsRequest>
{
"task": {
"flowRun": {
"flow": {
"id": "dd3cd2e7-2ede-49c6-945f-e7b2a2f25541"
}
}
},
"schedule": {
"frequency": "Daily",
"frequencyDetails": {
"start": "12:30:00",
"end": "23:30:00",
"intervals": [
{
"hours": "4"
},
{
"weekDay": "Monday"
},
{
"weekDay": "Wednesday"
}
]
}
}
}
Request Attributes
flow.id
|
(Required)The LUID of the flow the task is being scheduled for. |
schedule frequency
|
(Required to create subscription) enumeration: The scheduled frequency for triggering the task. Valid values include:
|
||||||||||
frequencyDetails start
|
(Required to create subscription) time: If the schedule frequency is Daily, Weekly, or Monthly , then start
is the time of day on which scheduled jobs should run. If the frequency is Hourly , then start is the beginning of the
time range during which jobs should be started. The valid format is HH:MM:SS .
|
||||||||||
frequencyDetails end
|
(Required to create subscription) time: If the schedule frequency is
|
||||||||||
interval {interval type}
|
(Required to create subscription) string: Defines when and how often a scheduled job executes within the time parameters set in the start and end
values of the frequencyDetails of the schedule . The type and valid values for
an interval expression depend on the declared frequency of the schedule as follows:
|
cURL Request Example
curl "http://MY-SERVER/api/3.24/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/datasources/1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d/connections" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"
Response Code
200
Response Body
<tsResponse>
<task>
<flowRun id="4d49655a-0f3a-45cc-ba61-b108a763e83a"
priority="50"
consecutiveFailedCount="0"
type="RunFlowTask">
<schedule id="1060dcb7-fef7-4fb1-8d3b-d0f042932d1a"
name="SSS_e95a9d25-c616-4542-87b6-3725975bdfbd"
state="Active"
priority="50"
createdAt="2024-04-09T18:54:12Z"
updatedAt="2024-04-09T18:54:12Z"
type="Flow"
frequency="Daily"
nextRunAt="2024-04-10T19:30:00Z"/>
<flow id="dd3cd2e7-2ede-49c6-945f-e7b2a2f25541"
name="olympic 1">
<parameters>
<parameter id="4f22c514-5b56-4400-a48a-f69d9be217a9"
type="integer"
name="output_count"
description="This is a parameter of a flow."
value="2"
isRequired="true">
<domain xsi:type="flowParameterAnyDomainType"
domainType="all"/>
</parameter>
</parameters>
</flow>
<flowRunSpec flowId="dd3cd2e7-2ede-49c6-945f-e7b2a2f25541">
<flowOutputSteps>
<flowOutputStep id="485c8b5f-5647-466c-b549-e38410b7c7c8"
name="Output"/>
</flowOutputSteps>
<flowParameterSpecs/>
</flowRunSpec>
</flowRun>
</task>
</tsResponse>
{
"task": {
"flowRun": {
"id": "4d49655a-0f3a-45cc-ba61-b108a763e83a",
"priority": "50",
"consecutiveFailedCount": "0",
"type": "RunFlowTask",
"schedule": {
"id": "1060dcb7-fef7-4fb1-8d3b-d0f042932d1a",
"name": "SSS_e95a9d25-c616-4542-87b6-3725975bdfbd",
"state": "Active",
"priority": "50",
"createdAt": "2024-04-09T18:54:12Z",
"updatedAt": "2024-04-09T18:54:12Z",
"type": "Flow",
"frequency": "Daily",
"nextRunAt": "2024-04-10T19:30:00Z"
},
"flow": {
"id": "dd3cd2e7-2ede-49c6-945f-e7b2a2f25541",
"name": "olympic 1",
"parameters": {
"parameter": {
"id": "4f22c514-5b56-4400-a48a-f69d9be217a9",
"type": "integer",
"name": "output_count",
"description": "This is a parameter of a flow.",
"value": "2",
"isRequired": "true",
"domain": {
"xsi_type": "flowParameterAnyDomainType",
"domainType": "all"
}
}
}
},
"flowRunSpec": {
"flowId": "dd3cd2e7-2ede-49c6-945f-e7b2a2f25541",
"flowOutputSteps": {
"flowOutputStep": {
"id": "485c8b5f-5647-466c-b549-e38410b7c7c8",
"name": "Output"
}
},
"flowParameterSpecs": []
}
}
}
}
Errors
HTTP status | error Code |
Condition | Details |
---|---|---|---|
400 | 400000 | Bad Request | The content of the request body is missing or incomplete, or contains malformed XML. |
401 | 401002 | Unauthorized Access | The authentication token provided in the request header was invalid or has expired. |
For more information, see Handling Errors.
Delete Flow
Deletes a flow. When a flow is deleted, its associated connections, the output and input steps, any associated scheduled tasks, and run history are also deleted.
URI
DELETE /api/api-version/sites/site-id/flows/flow-id
Parameter Values
api-version | The version of the API to use, such as 3.24 . For more information, see REST API and Resource Versions. |
site-id | The ID of the site that contains the flow. |
flow-id | The ID of the flow to delete. |
Request Body
None
Permissions
Tableau Server users who are not server administrators or site administrators can delete a flow for which they have Read (view) and Delete permissions (either explicitly or implicitly).
Response Code
204
Response Body
None
Version
Version 3.3 and later. For more information, see REST API and Resource Versions.
Errors
HTTP status | error Code |
Condition | Details |
---|---|---|---|
403 | 403004 | Deletion forbidden | A non-administrator user called this method but doesn't have Read (view) and Delete permission for the flow. |
404 | 404000 | Site not found | The site ID or URL namespace in the URI doesn't correspond to an existing site. |
404 | 404027 | Flow not found | The flow ID in the URI doesn't correspond to an existing flow. |
405 | 405000 | Invalid request method | Request type was not DELETE. |
For more information, see Handling Errors.
Delete Flow Permission
Deletes the specified permission from the specified flow for a group or user.
URI
DELETE /api/api-version/sites/site-id/flows/flow-id/permissions/groups/group-id/capability-name/capability-mode
DELETE /api/api-version/sites/site-id/flows/flow-id/permissions/users/user-id/capability-name/capability-mode
Parameter Values
api-version | The version of the API to use, such as 3.24 . For more information, see REST API and Resource Versions. |
site-id | The ID of the site that contains the flow. |
flow-id | The ID of the flow to remove the permission for. |
group-id | The ID of the group to remove the permission for. |
user-id | The ID of the user to remove the permission for. |
capability-name | The capability to remove the permission for. Valid capabilities for a flow are:
For more information, see Permissions. |
capability-mode | Allow to remove the allow permission, or Deny to remove the deny permission. This value is case sensitive. |
Request Body
None
Permissions
Tableau Server users who are not server administrators or site administrators can delete permissions from a flow only if they have ChangePermissions permission for flow (either explicitly or implicitly).
Response Code
204
Response Body
None
Version
Version 3.3 and later. For more information, see REST API and Resource Versions.
Errors
HTTP status | error Code |
Condition | Details |
---|---|---|---|
400 | 400009 | Invalid capability | The capability in the URI is invalid for a flow. Valid capabilities for a flow are ChangeHierarchy, ChangePermissions, Delete, Execute, ExportXml (Download), Read (view), and Write. |
403 | 403004 | Permissions setting forbidden | A non-administrator user called this method but doesn't have permission to set permissions on the flow. |
404 | 404000 | Site not found | The site ID in the URI doesn't correspond to an existing site. |
404 | 404002 | User not found | The user ID in the URI doesn't correspond to an existing user. |
404 | 404027 | Flow not found | The flow ID in the URI doesn't correspond to an existing flow. |
404 | 404012 | Group not found | The group ID in the URI doesn't correspond to an existing group. |
404 | 404013 | Capability not found | The capability in the URI doesn't correspond to a defined capability. This can apply to either an invalid capability name or a capability other than Allowor Denyat the end of the URI. |
404 | 404013 | Capability not assigned | The capability in the URI is not assigned to the specified user or group with the specified mode (Allowor Deny). |
405 | 405000 | Invalid request method | Request type was not DELETE. |
For more information, see Handling Errors.
Download Flow
Downloads a flow in .tfl or .tflx format.
URI
GET /api/api-version/sites/site-id/flows/flow-id/content
Parameter Values
api-version | The version of the API to use, such as 3.24 . For more information, see REST API and Resource Versions. |
site-id | The ID of the site that contains the flow. |
flow-id | The ID of the flow to download. |
Request Body
None
Permissions
Tableau Server users who are not server administrators or site administrators can download a flow only if they have download permission for the flow (either explicitly or implicitly).
Response Code
200
Response Body
None
Version
Version 3.3 and later. For more information, see REST API and Resource Versions.
Errors
HTTP status | error Code |
Condition | Details |
---|---|---|---|
403 | 403097 | Read forbidden | A non-administrator user attempted to download a flow, but the caller doesn't have Read permission. |
404 | 404000 | Site not found | The site ID in the URI doesn't correspond to an existing site. |
404 | 404027 | Flow not found | The flow ID in the URI doesn't correspond to an existing flow. |
405 | 405000 | Invalid request method | Request type was not GET. |
For more information, see Handling Errors.
Example
curl "http://MY-SERVER/api/3.24/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/flows/1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b/content" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" >
Response: The response is a file that contains the flow.
Get Flow Run
Gets a flow run.
URI
GET /api/api-version/sites/site-id/flows/runs/flow-run-id
Parameter Values
api-version | The version of the API to use, such as 3.24 . For more information, see REST API and Resource Versions. |
site-id | The ID of the site that contains the flow. |
flow-run-id | The ID of the flow run. |
Request Body
None
Response Code
200
Response Body
<tsResponse>
<flowRun id="flowRun_id"
flow id="flow_id"
status="status"
startedAt="DATE_TIME"
completedAt="DATE_TIME"
progress="100"
backgroundJobId="background_job_id"/>
<flowParameterRuns>
<parameterRuns parameter Id="parameter_id"
name="parameter_name"
description="parameter_description"
overrideValue="override_value"/>
</flowParameterRuns>
</flowRun>
</tsResponse>
The status attribute can be: Pending, InProgress, Success, Cancelled, or Failed.
Version
Version 3.10 and later. For more information, see REST API and Resource Versions.
Errors
HTTP status | error Code |
Condition | Details |
---|---|---|---|
403 | 403004 | Get forbidden | User does not have permissions to get the flow run. A user can view a flow run if they have permission to view the flow. |
404 | 404000 | Site not found | The site ID or URL namespace in the URI doesn't correspond to an existing site. |
404 | 404036 | Flow run not found | The flow run ID in the URI doesn't correspond to an existing flow run. |
405 | 405000 | Invalid request method | Request type was not GET. |
For more information, see Handling Errors.
Get Flow Runs
Get flow runs.
URI
GET /api/api-version/sites/site-id/flows/runs
GET /api/api-version/sites/site-id/flows/runs?filter=filter-expression
Parameter Values
api-version | The version of the API to use, such as 3.24 . For more information, see REST API and Resource Versions. |
site-id | The ID of the site. |
filter-expression | (Optional) An expression that lets you specify a subset to return. You can filter on predefined fields such as the userId of the user who started the flow run, flowId , progress , startedAt , and completedAt . You can include multiple filter expressions. For more information, see Filtering and Sorting. |
Request Body
None
Response Code
200
Response Body
<tsResponse>
<flowRuns>
<flowRuns id="flowRuns_id"
flow id="flow_id"
status="status"
startedAt="DATE_TIME"
completedAt="DATE_TIME"
progress="100"
backgroundJobId="background_job_id"/>
<flowParameterRuns>
<parameterRuns parameterId="parameter_id"
name="parameter_name"
description="parameter_description"
overrideValue="override_value"/>
</flowParameterRuns>
</flowRuns>
... additional flow runs....
</tsResponse>
The status attribute can be: Pending, InProgress, Success, Cancelled, or Failed.
Version
Version 3.10 and later. For more information, see REST API and Resource Versions.
Errors
HTTP status | error Code |
Condition | Details |
---|---|---|---|
403 | 403004 | Get forbidden | User does not have permissions to get the flow run. |
404 | 404000 | Site not found | The site ID or URL namespace in the URI doesn't correspond to an existing site. |
404 | 404002 | User not found | The user ID in the filter doesn't correspond to an existing user. |
405 | 405000 | Invalid request method | Request type was not GET. |
For more information, see Handling Errors.
Get Flow Run Task
Returns information about the specified flow run task. This method shows you information about the scheduled task for the flow.
URI
GET /api/api-version/sites/site-id/tasks/runFlow/task-id
Parameter Values
api-version | The version of the API to use, such as 3.24 . For more information, see REST API and Resource Versions. |
site-id | The ID of the site that the user is a member of. |
task-id | The ID of the scheduled flow run task that you want information about. |
Request Body
None
Permissions
Tableau Server users who are not server administrators or site administrators can only access the list of scheduled flow run tasks that they own.
Response Code
200
Response Body
<tsResponse>
<task>
<flowRun id="flowRun_id"
priority="nn"
consecutiveFailedCount="n"
type="RunFlowTask">
<schedule id="schedule_id"
name="schedule_name"
state="state"
priority="nn"
createdAt="DATE_TIME"
updatedAt="DATE_TIME"
type="flowRun"
frequency="frequency"
nextRunAt="DATE_TIME"/>
<flow id="flow_id"
name="flow_name"/>
<parameters>
<parameter id="parameter_id"
type="data_type"
name="parameter_name"
description="parameter_description"
value="parameter_value"
isRequired="true-or-false">
<domain xsi:type="flowParameterListDomainType-or-flowParameterAnyDomainType"
domainType="domain_type">
</domain>
</parameter>
</parameters>
</flowRun>
</task>
</tsResponse>
Version
Version 3.3 and later. For more information, see REST API and Resource Versions.
Errors
HTTP status | error Code |
Condition | Details |
---|---|---|---|
403 | 403004 | Operation unauthorized | The user is not authorized to get the task. |
404 | 404026 | Task not found | The task ID in the URI doesn't correspond to an existing task. |
405 | 405000 | Invalid request method | Request type was not GET. |
For more information, see Handling Errors.
Example
curl "http://MY-SERVER/api/3.24/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/tasks/runFlow/1bff10bb-57ae-43df-8774-a86d14aef432" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"
Example response:
<tsResponse version-and-namespace-settings> <task> <flowRun id="1bff10bb-57ae-43df-8774-a86d14aef432" priority="50" consecutiveFailedCount="2" type="RunFlowTask"> <schedule id="36d6fab2-2a0a-432e-b464-9fe4229a9937" name="Every 2 Minutes - Only use for failing (to be suspended) flows!" state="Active" priority="50" createdAt="2018-11-08T21:57:49Z" updatedAt="2018-11-09T18:12:09Z" type="Flow" frequency="Hourly" nextRunAt="2018-11-09T18:14:00Z"/> <flow id="8a320dca-9151-41ea-8474-a0bb71961cc0" name="allUseCaseTFLX2"/> <parameters> <parameter id="ebfad780-c19f-42a2-822a-406468269a02" type="string" name="Region" description="" value="North" isRequired="false"> <domain xsi:type="flowParameterListDomainType" domainType="any"> </domain> </parameter> </parameters> </flowRun> </task> </tsResponse>
Get Flow Run Tasks
Returns a list of scheduled flow tasks for the site.
URI
GET /api/api-version/sites/site-id/tasks/runFlow
Parameter Values
api-version | The version of the API to use, such as 3.24 . For more information, see REST API and Resource Versions. |
site-id | The ID of the site that the user is a member of. |
Request Body
None
Permissions
Tableau Server users who are not server administrators or site administrators can only access the list of scheduled flow tasks for the flows that they own.
Response Code
200
Response Body
<tsResponse>
<tasks>
<task>
<flowRun id="flowRun_id"
priority="nn"
consecutiveFailedCount="n"
type="RunFlowTask">
<schedule id="schedule_id"
name="schedule_name"
state="state"
priority="nn"
createdAt="DATE_TIME"
updatedAt="DATE_TIME"
type="flowRun"
frequency="frequency"
nextRunAt="DATE_TIME" />
<flow id="flow_id"/>
<parameters>
<parameter id="parameter_id"
type="data_type"
name="parameter_name"
description="parameter_description"
value="parameter_value"
isRequired="true-or-false">
<domain xsi:type="flowParameterListDomainType-or-flowParameterAnyDomainType"
domainType="domain_type">
</domain>
</parameter>
</parameters>
</flowRun>
</task>
... additional tasks ...
</tasks>
</tsResponse>
Version
Version 3.3 and later. For more information, see REST API and Resource Versions.
Errors
HTTP status | error Code |
Condition | Details |
---|---|---|---|
405 | 405000 | Invalid request method | Request type was not GET. |
For more information, see Handling Errors.
Example
curl "http://MY-SERVER/api/3.24/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/tasks/runFlow" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"
Example response:
<tsResponse version-and-namespace-settings>
<tasks>
<task>
<flowRun id="1bff10bb-57ae-43df-8774-a86d14aef432" priority="50" consecutiveFailedCount="2" type="RunFlowTask">
<schedule id="36d6fab2-2a0a-432e-b464-9fe4229a9937" name="Every 2 Minutes - Only use for failing (to be suspended) flows!" state="Active" priority="50" createdAt="2018-11-08T21:57:49Z" updatedAt="2018-11-09T17:30:08Z" type="Flow" frequency="Hourly" nextRunAt="2018-11-09T17:32:00Z"/>
<flow id="8a320dca-9151-41ea-8474-a0bb71961cc0" name="allUseCaseTFLX2"/>
<parameters>
<parameter id="ebfad780-c19f-42a2-822a-406468269a02" type="string" name="Region" description="" value="North" isRequired="false">
<domain xsi:type="flowParameterListDomainType" domainType="any">
</domain>
</parameter>
</parameters>
</flowRun>
</task>
<task>
<flowRun id="f11741cb-9646-4fb8-bbac-6d099c8d56b9" priority="50" consecutiveFailedCount="2" type="RunFlowTask">
<schedule id="36d6fab2-2a0a-432e-b464-9fe4229a9937" name="Every 2 Minutes - Only use for failing (to be suspended) flows!" state="Active" priority="50" createdAt="2018-11-08T21:57:49Z" updatedAt="2018-11-09T17:30:08Z" type="Flow" frequency="Hourly" nextRunAt="2018-11-09T17:32:00Z"/>
<flow id="8a320dca-9151-41ea-8474-a0bb71961cc0" name="allUseCaseTFLX2"/>
<flowParameterSpecs/>
</flowRun>
</task>
<task>
<flowRun id="357aaf2b-758d-4feb-a447-822528635a67" priority="44" consecutiveFailedCount="2" type="RunFlowTask">
<schedule id="6d4e61d0-2e2f-4f48-abc8-0695b95a5287" name="Every 15 mins!" state="Active" priority="50" createdAt="2018-11-08T20:45:47Z" updatedAt="2018-11-09T17:30:08Z" type="Flow" frequency="Hourly" nextRunAt="2018-11-09T17:45:00Z"/>
<flow id="d00700fe-28a0-4ece-a7af-5543ddf38a82" name="SQLServerUserNamePassword Good"/>
<flowParameterSpecs/>
</flowRun>
</task>
</tasks>
</tsResponse>
Get Linked Task
Returns information about a specific linked task. This method shows you information about the scheduled linked task
URI
GET /api/api-version/sites/site-id/tasks/linked/linked-task-id
Parameter Values
api-version | The version of the API to use, such as 3.24 . For more information, see REST API and Resource Versions. |
site-id | The ID of the site that the user is a member of. |
linked-task-id | The ID of the scheduled linked task that you want information about. |
Request Body
None
Permissions
All Tableau users can view linked tasks information, but can only see information about the flows in the response body if they have permissions to flows included in the linked task.
Response Code
200
Response Body
<tsResponse>
<linkedTasks id= "linkedTasks-id"
numSteps="number-of-steps">
<schedule id="schedule_id"
name="schedule-name"
state="Active-or-Suspended"
priority="priority"
createdAt="datetime-created"
updatedAt="datetime-updated"
type="schedule-type"
frequency="frequency"
nextRunAt="datetime-nextrun"/>
<linkedTaskSteps>
<linkedTaskSteps id="linked-tasks-step-id>
stepNumber="step-number"
stopDownstreamTasksOnFailure="true-or-false"/>
...additional linked tasks steps...
<task>
<flowRun id="flow-run-id"
priority="priority"
consecutiveFailedCount="consecutive-failed-count"
type="task-type">
<flow id = flow-id"
name="flow-name"
</flowRun>
</task>
</linkedTaskSteps>
...additional linked tasks steps...
</linkedTasksSteps>
</linkedTasks>
</tsResponse>
Version
Version 3.15 and later. For more information, see REST API and Resource Versions.
Errors
HTTP status | error Code |
Condition | Details |
---|---|---|---|
403 | 403004 | Operation unauthorized | The user is not authorized to get the task. |
404 | 404045 | Linked task not found | The task ID in the URI doesn't correspond to an existing linked task. |
405 | 405000 | Invalid request method | Request type was not GET. |
For more information, see Handling Errors.
Example
curl "http://MY-SERVER/api/3.24/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/tasks/linked/1bff10bd-57ae-37df-8774-a86d14aef432" -X GET -H "X-Tableau-Auth:12ab34cd56ef98ab90ce12ef34ab52cd"
Example response:
<tsResponse version-and-namespace-settings> <linkedTasks id="18d267af-4c40-4dz6-8234-6ag8c3dea67f" numSteps="2"> <schedule id="3ee04ae9-4dbf-45b5-a6d6-18fa19f2jb8a" name="Run Flow - Every Sunday - 4:00PM" state="Active" priority="50" createdAt="2021-01-21T19:15:53Z" updatedAt="2022-02-27T16:00:59Z" type="Flow" frequency="Weekly" nextRunAt="2022-03-06T16:00:00Z"/> <linkedTaskSteps> <linkedTaskSteps id="738fffc7-6a21-4af5-b49e-2c47f51480d2" stepNumber="1" stopDownstreamTasksOnFailure="true"> <task> <flowRun id="690c3b2c-a309-4683-9e6e-166517dc8598" priority="50" consecutiveFailedCount="0" type="RunFlowTask"> <flow id="56809d67-aca9-4f08-9fdc-4b6473c3ff02" name="r-3"/> </flowRun> </task> </linkedTaskSteps> </tsResponse>
Get Linked Tasks
Returns a list of scheduled linked tasks for a site.
URI
GET /api/api-version/sites/site-id/tasks/linked
Parameter Values
api-version | The version of the API to use, such as 3.24 . For more information, see REST API and Resource Versions. |
site-id | The ID of the site that the user is a member of. |
Request Body
None
Permissions
All Tableau users can view linked tasks information, but can only see information about the flows in the response body if they have permissions to flows included in the linked task.
Response Code
200
Response Body
<tsResponse>
<linkedTasks>
<linkedTasks id= "linkedTasks-id"
numSteps="number-of-steps">
<schedule id="schedule_id"
name="schedule-name"
state="Active-or-Suspended"
priority="priority"
createdAt="datetime-created"
updatedAt="datetime-updated"
type="schedule-type"
frequency="frequency"
nextRunAt="datetime-nextrun"/>
<linkedTaskSteps>
<linkedTaskSteps id="linked-tasks-step-id>
stepNumber="step-number"
stopDownstreamTasksOnFailure="true-or-false"/>
...additional linked tasks steps...
<task>
<flowRun id="flow-run-id"
priority="priority"
consecutiveFailedCount="consecutive-failed-count"
type="task-type">
<flow id = flow-id"
name="flow-name"
</flowRun>
</task>
</linkedTaskSteps>
...additional linked tasks steps...
</linkedTasksSteps>
... additional linked tasks ...
</linkedTasks>
</tsResponse>
Version
Version 3.15 and later. For more information, see REST API and Resource Versions.
Errors
HTTP status | error Code |
Condition | Details |
---|---|---|---|
400 | 400154 | Generic query linked task error | Could not get a list of linked tasks for some reason other than the ones specified below. |
403 | 403155 | Linked tasks disabled | Linked tasks has been disabled for your site or server. |
403 | 403004 | Operation unauthorized | You do not have permissions to see the list of linked tasks |
405 | 405000 | Invalid request method | Request type was not GET. |
For more information, see Handling Errors.
Example
curl "http://MY-SERVER/api/3.24/sites/9a6b7c6d-5e4f-4a2b-1c0d-9e8f7s6b5c4d/tasks/linked" -X GET -H "X-Tableau-Auth:12ab34cd56ef98ab90ce12ef34ab52cd"
Example response:
<tsResponse version-and-namespace-settings>
<linkedTasks>
<linkedTasks id="18d267af-4c40-4dz6-8234-6ag8c3dea67f"
numSteps="2">
<schedule id="3ee04ae9-4dbf-45b5-a6d6-18fa19f2jb8a"
name="Run Flow - Every Sunday - 4:00PM"
state="Active" priority="50"
createdAt="2021-01-21T19:15:53Z"
updatedAt="2022-02-27T16:00:59Z"
type="Flow" frequency="Weekly"
nextRunAt="2022-03-06T16:00:00Z"/>
<linkedTaskSteps>
<linkedTaskSteps id="738fffc7-6a21-4af5-b49e-2c47f51480d2"
stepNumber="1"
stopDownstreamTasksOnFailure="true">
<task>
<flowRun id="690c3b2c-a309-4683-9e6e-166517dc8598"
priority="50"
consecutiveFailedCount="0"
type="RunFlowTask">
<flow id="56809d67-aca9-4f08-9fdc-4b6473c3ff02" name="r-3"/>
</flowRun>
</task>
</linkedTaskSteps>
<linkedTaskSteps id="b9668563-e2c3-414d-b461-084a3d951cc5"
stepNumber="2"
stopDownstreamTasksOnFailure="true">
<task>
<flowRun id="2bb8e959-f5da-4691-903e-be73eed08a4c"
priority="50"
consecutiveFailedCount="0"
type="RunFlowTask">
<flow id="19ed906f-4752-4f89-a3ca-19b406efd596"
name="flights"/>
</flowRun>
</task>
</linkedTaskSteps>
</linkedTasks>
<linkedTasks id="abf4c0d2-0b5a-4dd1-9667-70b22bd73fe9"
numSteps="2">
<schedule id="92811890-d91c-456a-83b6-94db7d7041be"
name="Run Flow - Weekday 2:00AM"
state="Active" priority="50"
createdAt="2021-01-21T19:15:52Z"
updatedAt="2022-03-01T02:00:59Z"
type="Flow"
frequency="Weekly"
nextRunAt="2022-03-02T02:00:00Z"/>
<linkedTaskSteps>
<linkedTaskSteps id="3061807b-e0f4-48ab-bbdd-7e032ff25858"
stepNumber="1"
stopDownstreamTasksOnFailure="true">
<task>
<flowRun id="c914cf4c-23e4-437c-b25b-11735bf586nf"
priority="50"
consecutiveFailedCount="0"
type="RunFlowTask">
<flow id="5a421e12-6dc4-42b5-9723-e8e667c728f3"
name="Test3"/>
</flowRun>
</task>
</linkedTaskSteps>
<linkedTaskSteps id="ed515d51-7715-4d3f-zf16-46e6f90cd5cf"
stepNumber="2"
stopDownstreamTasksOnFailure="true">
<task>
<flowRun id="fb945078-85c3-4f78-8214-f6fb3374d67e"
priority="50"
consecutiveFailedCount="2"
type="RunFlowTask">
<flow id="1ea76ax2-4ef3-49d3-9892-f1840b6e55da"
name="Superstore Flow"/>
</flowRun>
</task>
</linkedTaskSteps>
</linkedTaskSteps>
</linkedTasks>
</linkedTasks>
</tsResponse>
Publish Flow
Publishes a flow on the specified site. To make other changes to a published flow, call Update Flow or Update Flow Connection.
You can do publish a flow in a single request or in multiple parts.
To publish a flow in a single request you include the content of the workbook file in the body of the request. The maximum size of a file that can be published in a single request is 64 MB.
To publish a flow in multiple parts, you initiate a file upload by calling Initiate File Upload(Link opens in a new window), send portions of the file to the server using Append to File Upload(Link opens in a new window), and then commit the upload by calling Publish Flow. In this case, Publish Flow doesn't contain the file to publish but the uploadSessionId
and the flowType
parameters are required.
URI
POST /api/api-version/sites/site-id/flows
POST /api/api-version/sites/site-id/flows?overwrite=overwrite-flag
POST /api/api-version/sites/site-id/flows?overwrite=overwrite-flag&uploadSessionId=upload-session-id&flowType=flow-file-type
Parameter Values
api-version | The version of the API to use, such as 3.24 . For more information, see REST API and Resource Versions. |
site-id | The ID of the site to publish to. |
overwrite-flag | (Optional) true to overwrite a flow that has the same name, or false to fail if the specified flow already exists. The default is false. If overwrite-flag is set to true but the flow doesn't already exist, the operation succeeds. |
upload-session-id | If you are calling this method to commit a file that was uploaded in parts, this value contains the upload session ID that was generated by a call to Initiate File Upload. If this value is not included, the server assumes that the body of the request contains the file to be published. |
flow-file-type | tfl or tflx to indicate whether you have uploaded a flow file (tfl) or a packaged flow file (tflx). This value is only necessary and required if you upload a file in multiple parts. In the Publish Flow call after completing file upload, specify the file type. |
Publishing a file in the Request Body
--boundary-stringContent-Disposition:
name="request_payload"
Content-Type: text/xml
<tsRequest>
<flow name="flow-name" >
<project id="project-id" />
</flow>
<connections>
<connection id="abc"
serverAddress="server-address"
serverPort="port-number">
<connectionCredentials
name="connection-username"
password="connection-password"
embed="embed-flag"
oAuth="oauth-flag" />
</connection>
</connections>
</tsRequest>
--boundary-string
Content-Disposition: name="tableau_flow"; filename="flow-file-name"
Content-Type: application/octet-stream
content-of-flow-file
--boundary-string--
Attribute Values
name | The name to assign to the flow when it is saved on the server. |
description | The description of the flow. |
server-address | Specify the server address for an input connections. |
port-number | Specify the port number for input connections. |
connection-username | (Optional) If the flow input connections require credentials, the <connectionCredentials> elements are included and this attribute specifies the connection username. If the element is included but is not required, the server ignores the element and its attributes. |
connection-password | (Optional) If the flow input connections require credentials, the <connectionCredentials> elements are included and this attribute specifies the connection password. If the element is included but is not required, the server ignores the element and its attributes. |
embed-flag | (Optional) If the input connection requires credentials, the <connectionCredentials> element is included. Setting this attribute to Trueinstructs the server to save the credentials. |
project-id | The ID of the project to assign the flow to. |
content-of-flow-file | The file itself if you are including it in the request body. |
Permissions
Users who are not server administrators or site administrators can publish a flow only if the flow belongs to a project that they have permissions to publish to, have a site role that allows publishing and have write permissions on the flow this is an overwrite.
Required scope for JWT authorization
Introduced in Tableau Cloud June 2022 (API 3.16) and Tableau Server 2022.3 (API 3.17).
Authorize use of this method in your connected app by including this scope in its JSON Web Token (JWT). For more information, see Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Cloud Help or Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Server Help.
tableau:flows:create
Response Code
201
Response Body
<tsResponse>
<flow id="770a1cf8-6abe-4bc3-b0b8-59c4b15ce959"
name="ShortTermRentalNola222"
description=""
webpageUrl="http://localhost/#/flows/3"
fileType="tflx" createdAt="2018-11-20T19:28:58Z"
updatedAt="2018-11-20T19:28:58Z">
<project id="9077e04c-ece4-11e8-aa58-df538c72f42f"
name="Default" />
<owner id="5a39de9c-4eb0-47a7-88f7-2e78ddd58c6b" />
</flow>
</tsResponse>
Version
Version 3.3 and later. For more information, see REST API and Resource Versions.
Errors
HTTP status | error Code |
Condition | Details |
---|---|---|---|
400 | 400000 | Malformed request body | The XML content in the MIME multipart request is not empty. |
400 | 400089 | Missing flow name | Flow name is required and was not specified. |
403 | 403007 | Invalid permissions | The caller does not have the necessary permissions to publish the flow. |
400 | 400090 | Missing flow payload | The flow information (the structure containing the flow description, flow project) was not included in the request body. |
400 | 400086 | Invalid flow attachment | The name of the flow doesn't end in .tfl or .tflx. |
400 | 400087 | Generic flow publishing error | The flow could not be published for some other reason than those specified earlier. |
409 | 409041 | Flow already found in destination | The flow name should be unique, or the overwrite flag parameter should be set to true. |
403 | 403008 | Insufficient storage quota | The flow could not be published because there is not enough storage remaining on the server to accommodate its size. |
404 | 404000 | Site not found | The site ID in the URI doesn't correspond to an existing site. |
404 | 404005 | Project not found | The project ID in the request body doesn't correspond to an existing project on the site. |
404 | 404027 | Flow not found | The flow ID in the URI doesn't correspond to an existing flow. |
405 | 405000 | Invalid request method | Request type was not POST. |
For more information, see Handling Errors.
Query Flow
Returns information about the specified flow, including information about the project, owner, and output steps.
Note: After you create a resource, the server updates its search index. If you make a query immediately to see a new resource, the query results might not be up to date.
URI
GET /api/api-version/sites/site-id/flows/flow-id
Parameter Values
api-version | The version of the API to use, such as 3.24 . For more information, see REST API and Resource Versions. |
site-id | The ID of the site that contains the flow. |
flow-id | The ID of the flow to return information about. |
Request Body
None
Permissions
Tableau Server users who are not server administrators or site administrators can query a flow only if they have Read(view) permission for the flow (either explicitly or implicitly).
Response Code
200
Response Body
<tsResponse>
<flowOutputSteps>
<flowOutputStep id = "flow-output-step id"
name = "flow-name">
...additional output steps...
</flowOutputSteps>
<flow id = "flow-id">
<project id = "project-id">
<owner id = "owner-id">
<tags/>
<parameters>
<parameter id="parameter-id" type="data type" name="parameter name" description=" parameter description" value="current value" isRequired="true/false">
<domain xsi:type="flowParameterDomainType" domainType="domain type">
</domain>
<parameter>
...additional parameters...
<parameters>
</flow>
</tsResponse>
Note: Parameters is only shown in the response if parameters are enabled on the site and the flow contains parameters.
Version
Version 3.3 and later. For more information, see REST API and Resource Versions.
Errors
HTTP status | error Code |
Condition | Details |
---|---|---|---|
403 | 403004 | Read forbidden | A non-administrator user attempted to query the flow, but the caller doesn't have Read permission. |
404 | 404000 | Site not found | The site ID in the URI doesn't correspond to an existing site. |
404 | 404027 | Flow not found | The flow ID in the URI doesn't correspond to an existing flow. |
405 | 405000 | Invalid request method | Request type was not GET. |
405 | 405000 | Invalid request method | Request type was not GET. |
For more information, see Handling Errors.
Example
curl "http://MY-SERVER/api/3.24/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/flows/ d00700fe-28a0-4ece-a7af-5543ddf38a82" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"
Example response:
<tsResponse version-and-namespace-settings>
<flowOutputSteps>
<flowOutputStep id="5e4c9a74-d29a-4f62-baa5-97c443440dfc" name="CoffeeChainOutputCSV"/>
<flowOutputStep id="baa85bce-6aab-434a-8070-72625ded8cb6" name="CoffeeChainOutputHyper"/>
<flowOutputStep id="2f5da1ba-4a40-44a4-9201-7db6ce089811" name="CoffeeChainOutputTDE"/>
</flowOutputSteps>
<flow id="d00700fe-28a0-4ece-a7af-5543ddf38a82" name="SQLServerUserNamePassword Good" description="" webpageUrl="http://tpqawin01/#/flows/3" fileType="tflx" createdAt="2018-11-06T04:57:55Z" updatedAt="2018-11-06T21:31:00Z">
<project id="6f8a2966-e173-11e8-ae74-ffd84c19d7f3" name="Default"/>
<owner id="711e59cf-d1c0-446e-be48-3673ae067f7b"/>
<tags/>
<parameters>
<parameter id="d6785a99-e997-4f9c-b0eb-91a02371621b" type="string" name="String Param" description="String test parameter" value="string 2" isRequired="false">
<domain xsi:type="flowParameterListDomainType" domainType="all">
</parameter>
</parameters>
</flow>
</tsResponse>
Query Flows for a Site
Returns the flows on a site. If the user is not an administrator, the method returns just the flows that the user has permissions to view.
URI
GET /api/api-version/sites/site-id/flows
GET /api/api-version/sites/site-id/flows?filter=filter-expression
GET /api/api-version/sites/site-id/flows?sort=sort-expression
GET /api/api-version/sites/site-id/flows?pageSize=page-size&pageNumber=page-number
Parameter Values
api-version | The version of the API to use, such as 3.24 . For more information, see REST API and Resource Versions. |
site-id | The ID of the site that contains the flows. |
filter-expression | (Optional) An expression that lets you specify a subset of flows to return. You can filter on predefined fields such as name, tags, and createdAt. You can include multiple filter expressions. For more information, see Filtering and Sorting. |
sort-expression | (Optional) An expression that lets you specify the order in which flow information is returned. If you do not specify a sort expression, the sort order of the information that's returned is undefined. For more information, see Filtering and Sorting. |
page-size | (Optional) The number of items to return in one response. The minimum is 1. The maximum is 1000. The default is 100. For more information, see Paginating Results. |
page-number | (Optional) The offset for paging. The default is 1. For more information, see Paginating Results. |
Note: The filter and sort parameters can be combined with each other and with paging parameters using an ampersand (&
).
Request Body
None
Permissions
Tableau Server users who are not server administrators or site administrators can get flows that they have Read (view) permissions for (either explicitly or implicitly).
Response Code
200
Response Body
<tsResponse>
<pagination pageNumber="page-number"
pageSize="page-size"
totalAvailable="total-available"/>
<flows>
<flow id="flow-id"
name="flow-name"
description="flow-description"
webpageUrl="web-page-url"
fileType="file-type"
createdAt="datetime-created"
updatedAt="datetime-updated">
<project id="project-id" name="project-name"/>
<owner id="owner-id"/>
<tags/>
<parameters>
<parameter id="parameter-id" type="data type" name="parameter name" description="parameter description" value="current value" isRequired="false">
<domain xsi:type="flowParameterListDomainType" domainType="all">
</domain>
</parameter>
<parameters>
</flow>
... additional flows ...
</flows>
</tsResponse>
The datetime-created and datetime-updated attribute values are returned in UTC format (YYYY-MM-DDTHH:MM:SSZ).
Version
Version 3.3 and later. For more information, see REST API and Resource Versions.
Errors
HTTP status | error Code |
Condition | Details |
---|---|---|---|
400 | 400006 | Invalid page number | The page number is not an integer, is less than one, or is greater than the final page number for users at the requested page size. |
400 | 400007 | Invalid page size | The page size parameter is not an integer, or is less than one. |
403 | 403101 | Read forbidden | A non-administrator user attempted to query flows for the site, but the caller doesn't have Read permission. |
404 | 404000 | Site not found | The site ID in the URI doesn't correspond to an existing site. |
405 | 405000 | Invalid request method | Request type was not GET. |
For more information, see Handling Errors.
Example
curl "http://MY-SERVER/api/3.24/sites/9954070a-581d-40fa-ae73-e815ce8b0562/flows" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"
Example response:
<tsResponse version-and-namespace-settings> <pagination pageNumber="1" pageSize="100" totalAvailable="7"/> <flows> <flow id="d00700fe-28a0-4ece-a7af-5543ddf38a82" name="SQLServerUserNamePassword Good" description="" webpageUrl="http://tpqawin01/#/flows/3" fileType="tflx" createdAt="2018-11-06T04:57:55Z" updatedAt="2018-11-06T21:31:00Z"> <project id="6f8a2966-e173-11e8-ae74-ffd84c19d7f3" name="Default"/> <owner id="711e59cf-d1c0-446e-be48-3673ae067f7b"/> <tags/> <parameters/> </flow> <flow id="c1e82fe3-e7cf-4bd5-afd3-799b1e8aac27" name="broken_loom_doc_2" description="" webpageUrl="http://tpqawin01/#/flows/26" fileType="tflx" createdAt="2018-11-06T18:19:54Z" updatedAt="2018-11-06T18:19:54Z"> <project id="6f8a2966-e173-11e8-ae74-ffd84c19d7f3" name="Default"/> <owner id="711e59cf-d1c0-446e-be48-3673ae067f7b"/> <tags/> <parameters> <parameter id="d6785a99-e997-4f9c-b0eb-91a02371621b" type="string" name="String Param" description="String parameter test" value="string 2" isRequired="false"> <domain xsi:type="flowParameterListDomainType" domainType="all"> </parameter> </parameters> </flow> <flow id="d4eccc71-5cbd-4753-a807-d3ea9256aee1" name="Partner Influence" description="configured by ibeekun" webpageUrl="http://tpqawin01/#/flows/34" fileType="tflx" createdAt="2018-11-06T22:46:57Z" updatedAt="2018-11-06T22:46:57Z"> <project id="6f8a2966-e173-11e8-ae74-ffd84c19d7f3" name="Default"/> <owner id="711e59cf-d1c0-446e-be48-3673ae067f7b"/> <tags/> <parameters/> </flow> <flow id="82aefd39-ae37-4ad8-a44c-391563f12e18" name="Omniture logs" description="configured by testuser" webpageUrl="http://mytestServer/#/flows/35" fileType="tflx" createdAt="2018-11-06T22:47:18Z" updatedAt="2018-11-06T22:47:18Z"> <project id="6f8a2966-e173-11e8-ae74-ffd84c19d7f3" name="Default"/> <owner id="711e59cf-d1c0-446e-be48-3673ae067f7b"/> <tags> <parameters/> </flow> <flow id="b527d896-b71e-4953-b085-2afecccea427" name="NY Parking Tickets" description="configured by ibeekun" webpageUrl="http://tpqawin01/#/flows/37" fileType="tflx" createdAt="2018-11-07T00:19:48Z" updatedAt="2018-11-07T00:19:48Z"> <project id="6f8a2966-e173-11e8-ae74-ffd84c19d7f3" name="Default"/> <owner id="711e59cf-d1c0-446e-be48-3673ae067f7b"/> <tags/> <parameters/> </flow> <flow id="ddcd4f53-76b6-4af7-a050-fe3eef702317" name="Flow1" description="" webpageUrl="http://tpqawin01/#/flows/40" fileType="tfl" createdAt="2018-11-07T00:38:48Z" updatedAt="2018-11-07T00:38:48Z"> <project id="6f8a2966-e173-11e8-ae74-ffd84c19d7f3" name="Default"/> <owner id="711e59cf-d1c0-446e-be48-3673ae067f7b"/> </flow> <flow id="868eab1a-2b60-448a-9913-82e4522ab952" name="local-postgres-bad-pw" description="" webpageUrl="http://tpqawin01/#/flows/78" fileType="tflx" createdAt="2018-11-07T22:18:04Z" updatedAt="2018-11-07T22:18:04Z"> <project id="6f8a2966-e173-11e8-ae74-ffd84c19d7f3" name="Default"/> <owner id="711e59cf-d1c0-446e-be48-3673ae067f7b"/> <tags/> <parameters/> </flow> </flows> </tsResponse>
Query Flows for User
Returns the flows that the specified user owns in addition to those that the user has Read (view) permissions for.
Note: After you create a resource, the server updates its search index. If you make a query immediately to see a new resource, the query results might not be up to date.
URI
GET /api/api-version/sites/site-id/users/user-id/flows
GET /api/api-version/sites/site-id/users/user-id/flows?ownedBy=isOwner&pageSize=page-size&pageNumber=page-number
Parameter Values
api-version | The version of the API to use, such as 3.24 . For more information, see REST API and Resource Versions. |
site-id | The ID of the site that contains the user. |
user-id | The ID of the user to get flows for. |
isOwner | (Optional) trueto return only flows that the specified user owns, or falseto return all flows that the specified user has at least read access to. The default is false. |
page-size | (Optional) The number of items to return in one response. The minimum is 1. The maximum is 1000. The default is 100. For more information, see Paginating Results. |
page-number | (Optional) The offset for paging. The default is 1. For more information, see Paginating Results. |
Request Body
None
Permissions
All users can call this method, but the results of the call depend on the user's permissions. Server and site administrators see all flows for the specified user. If the isOwnerparameter is true, users who are not server or site administrators see the flows that they own on the site. If isOwnerparameter is false, users who are not server administrators see the flows that they have Read (view) permissions for.
Response Code
200
Response Body
<tsResponse>
<pagination pageNumber="page-number"
pageSize="page-size"
totalAvailable="total-available"/>
<flows>
<flow id="flow-id"
name="flow-name" description="flow-description"
webpageUrl="URL"
fileType="flow-file-type"
createdAt="Datetime-created"
updatedAt="Datetime-updated">
<project id="project-id" name="project-name"/>
<owner id="owner-id"/>
<tags/>
<parameters>
<parameter id="parameter-id" type="data type" name="parameter name" description="parameter description" value="current value" isRequired="false">
<domain xsi:type="flowParameterListDomainType" domainType="all">
</domain>
</parameter>
<parameters>
</flow>
... additional flows...
</flows>
</tsResponse>
The datetime-created and datetime-updated attribute values are returned in UTC format (YYYY-MM-DDTHH:MM:SSZ).
Version
Version 3.3 and later. For more information, see REST API and Resource Versions.
Errors
HTTP status | error Code |
Condition | Details |
---|---|---|---|
400 | 400006 | Invalid page number | The page number parameter is not an integer, is less than one, or is greater than the final page number for flows at the requested page size. |
400 | 400007 | Invalid page size | The page size parameter is not an integer, or is less than one. |
403 | 403014 | Page size exceeds upper limit | The page size parameter exceeds the system-wide upper limit of 1000. |
403 | 403101 | Read forbidden | A non-administrator user attempted to query flows for the user, but the caller doesn't have Read permission. |
404 | 404000 | Site not found | The site ID in the URI doesn't correspond to an existing site. |
404 | 404002 | User not found | The user ID in the URI doesn't correspond to an existing user. |
405 | 405000 | Invalid request method | Request type was not GET. |
For more information, see Handling Errors.
Example
curl "http://MY-SERVER/api/3.24/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/users/9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d/flows" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"
Example response:
<tsResponse version-and-namespace-settings>
<pagination pageNumber="1" pageSize="100" totalAvailable="41"/>
<flows>
<flow id="00795e57-0c0b-43c9-843f-6635d6577dec" name="several_excel_input_union2" description="" webpageUrl="http://tpqawin01/#/flows/263" fileType="tflx" createdAt="2018-11-09T20:01:04Z" updatedAt="2018-11-09T20:01:04Z">
<project id="6f8a2966-e173-11e8-ae74-ffd84c19d7f3" name="Default"/>
<owner id="303379e9-3b66-419c-a022-7179bc13892c"/>
</flow>
<flow id="467242c7-3d5a-4ba8-b4c3-58b5aecc084d" name="Superstore_Test_ER" description="testing direct connection" webpageUrl="http://tpqawin01/#/flows/124" fileType="tfl" createdAt="2018-11-08T21:30:44Z" updatedAt="2018-11-08T21:30:44Z">
<project id="6f8a2966-e173-11e8-ae74-ffd84c19d7f3" name="Default"/>
<owner id="711e59cf-d1c0-446e-be48-3673ae067f7b"/>
<tags/>
<parameters>
<parameter id="d6785a99-e997-4f9c-b0eb-91a02371621b" type="string" name="String Param" description="String parameter test" value="string 2" isRequired="false">
<domain xsi:type="flowParameterListDomainType" domainType="all">
</parameter>
</parameters>
</flow>
</flows>
</tsResponse>
Query Flow Connections
Returns a list of data connections for the specific flow.
URI
GET /api/api-version/sites/site-id/flows/flow-id/connections
Parameter Values
api-version | The version of the API to use, such as 3.24 . For more information, see REST API and Resource Versions. |
site-id | The ID of the site that contains the flow. |
flow-id | The ID of the flow to return connection information about. |
Request Body
None
Permissions
Tableau Server users who are not server administrators or site administrators can query a flow only if they have Read(view) permission for the flow (either explicitly or implicitly).
Response Code
200
Response Body
<tsResponse >
<connections>
<connection id="connection-id"
type="connection-type"
serverAddress="server-address"
userName="user-name"
embedPassword="true-or-false"/>
... additional connections ...
</connections>
</tsResponse>
Version
Version 3.3 and later. For more information, see REST API and Resource Versions.
Errors
HTTP status | error Code |
Condition | Details |
---|---|---|---|
403 | 403092 | Read forbidden | A user who is not a server administrator user attempted to query the flow connections, but the caller doesn't have Readpermission. |
404 | 404000 | Site not found | The site ID in the URI doesn't correspond to an existing site. |
404 | 404027 | Flow not found | The flow ID in the URI doesn't correspond to an existing flow. |
405 | 405000 | Invalid request method | Request type was not GET. |
For more information, see Handling Errors.
Example
curl "http://MY-SERVER/api/3.24/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/flows/1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d/connections" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"
Example response:
<tsResponse version-and-namespace-settings>
<connections>
<connection id="5fd1c1db-572f-4ebd-94e7-a09e212bc147" type="sqlserver" serverAddress="mySQLServer" userName="test" embedPassword="true"/>
<connection id="ed358ca5-f25b-43b4-8791-2dbf34631df6" type="tableau-server-site" serverAddress="http://testserver01" userName="" embedPassword="false"/>
</connections>
</tsResponse>
List Flow Permissions
Returns a list of permissions for the specific flow.
URI
GET /api/api-version/sites/site-id/flows/flow-id/permissions
Parameter Values
api-version | The version of the API to use, such as 3.24 . For more information, see REST API and Resource Versions. |
site-id | The ID of the site that contains the flow. |
flow-id | The ID of the flow to get permissions for. |
Request Body
None
Permissions
This method can only be called by server administrators and site administrators.
Response Code
200
Response Body
<tsResponse >
<permissions>
<flow id="flow-id" name="flow-name">
<owner id="owner-id"/>
</flow>
<granteeCapabilities>
<group id="group-id"/>
<capabilities>
<capability name="Read" mode="Allow"/>
<capability name="Write" mode="Allow"/>
... additional capabilities ...
</capabilities>
</granteeCapabilities>
</permissions>
</tsResponse>
Note: The parent element is included in the response only if the workbook's permissions are determined by project-level default permissions and project permissions are locked. Project permissions can be locked for a new project when you call Create Project(Link opens in a new window) or for an existing project by calling Update Project(Link opens in a new window). For more information, see Lock Content Permissions to the Project(Link opens in a new window).
Version
Version 3.3 and later. For more information, see REST API and Resource Versions.
Errors
HTTP status | error Code |
Condition | Details |
---|---|---|---|
404 | 404000 | Site not found | The site ID in the URI doesn't correspond to an existing site. |
404 | 404027 | Flow not found | The flow ID in the URI doesn't correspond to an existing flow. |
For more information, see Handling Errors.
Example
curl "http://MY-SERVER/api/3.24/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/flows/1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d/permissions" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"
Example response:
<tsResponse xmlns= version-and-namespace-settings>
<permissions>
<flow id="d00700fe-28a0-4ece-a7af-5543ddf38a82" name="SQLServerUserNamePassword Good">
<owner id="711e59cf-d1c0-446e-be48-3673ae067f7b"/>
</flow>
<granteeCapabilities>
<group id="6fd1dea0-e173-11e8-ae75-832f6a4756f0"/>
<capabilities>
<capability name="Read" mode="Allow"/>
<capability name="Write" mode="Allow"/>
</capabilities>
</granteeCapabilities>
</permissions>
</tsResponse>
Run Flow Now
Runs the specified flow.
This method runs the specified flow with all the output steps if none are specified. If you want to run only a subset of output steps, you can specify one or more output steps using the output-ids by using the Flow Methods. The Run Flow Now method is the equivalent of selecting a flow using the Tableau Server UI, and then selecting Run Now from the menu.
A flow task can be initiated by a REST API call, a tabcmd command, or a job calling the task on a schedule. A REST request to start a flow task will often fail if the task has been put in the task queue in any of these ways, or is already in progress. Running the flow for a suspended task using Run Flow Now will resume the task job.
Note:
- This method is unavailable if you don't have Data Management. For more information, see Tableau Prep Conductor.
- This method will fail and result in an error if your Server Administrator has disabled the RunNow setting for the site. For more information, see Tableau Server Settings(Link opens in a new window).
URI
POST /api/api-version/sites/site-id/flows/flow-id/run
POST /api/api-version/sites/site-id/flows/flow-id/run?flowOutputStepIds=flow-outputstep-id&flowRunMode=flow-run-mode
Parameter Values
api-version | The version of the API to use, such as 3.24 . For more information, see REST API and Resource Versions. |
site-id | The ID of the site that contains the flow. |
flow-id | The ID of the flow to update. |
Request Body
<tsRequest>
<flowRunSpec
flowId="flow id"
runMode="run mode">
<flowParameterSpecs>
<flowParameterSpec
parameterId="parameter id"
overrideValue="override value" />
</flowParameterSpecs>
<flowOutputSteps>
<flowOutputStep
id="flow output step id" />
</flowOutputSteps>
</flowRunSpec>
</tsRequest>
A request body with for running a flow with no parameters:
<tsRequest>
<flowRunSpec
flowId="flow id"
runMode="run mode">
<flowOutputSteps>
<flowOutputStep
id="flow output step id" />
</flowOutputSteps>
</flowRunSpec>
</tsRequest>
A request body for running a flow but not specifying output step (effectively running all output steps):
<tsRequest>
<flowRunSpec
flowId="flow id"
runMode="run mode">
<flowParameterSpecs>
<flowParameterSpec
parameterId="parameter id"
overrideValue="override value" />
</flowParameterSpecs>
</flowRunSpec>
</tsRequest>
Attribute Values
flow-id |
The ID of the flow to add to the schedule. This will include all the output steps in the flow and any output steps created in the future. |
flow-outputstep-id |
The ID of the output steps you want to run. This parameter is optional. If you don't specify the output steps, all the output steps in the flow will be included. You can specify one or more output steps. Use the Flow Methods method to get the list of flow-outputstep-ids. |
flow-run-mode |
The mode to use for running this flow, either full or incremental. This parameter is optional. If you don't specify an option the run mode will be full. The flow must be configured with incremental options on the input nodes to refresh incrementally. |
parameter-id |
The ID of the flow parameter. Use the Flow Methods method to get the flow parameter ID. A parameter is a global placeholder value such as a number, text value, or boolean value that can replace a constant value in a flow. Note: Parameters are optional and only relevant for flows that contain parameters and the parameter setting is enabled. For more information, see Run flows with parameters. |
overrideValue |
The run-time value for the flow parameter. You must specify this if the parameter is required. Use the Flow Methods method to see if the parameter is required and to get a list of allowed values if the parameter is expecting a value from an enumerated list. Note: Parameters are optional and only relevant for flows that contain parameters and the parameter setting is enabled. For more information, see Run flows with parameters. |
Note: You must specify the flow-id value in the URI. If you are using a request body to specify the attributes, you must also include the flow-id in the request body in addition to providing it in the URI.
Permissions
In addition to the owner of a flow, Tableau server administrators, site administrators, and project leaders can run flows within their scope. Users with a creator or explorer license that have been granted permissions by an administrator, leader or owner for a flow may also run it.
Response Code
200
Response Body
<tsResponse>
<job id="job-id"
mode="Asynchronous"
type="RunFlow"
createdAt="DateTime-CreatedAt">
<runFlowJobType flowRunId="flow-run-id">
<flow id="flow-id" name="flow-name"/>
</runFlowJobType>
</job>
</tsResponse>
Version
Version 3.3 and later. For more information, see REST API and Resource Versions.
Errors
HTTP status | error Code |
Condition | Details |
---|---|---|---|
400 | 400000 | Bad Request | The content of the request body is missing or incomplete, or contains malformed XML. |
400 | 400132 | Invalid flow run mode | The specified flow run mode is not valid. |
400 | 400148 | Invalid parameter override value | The run-time value specified is not valid. |
400 | 400149 | Parameter override value missing | The run-time value for the parameter was not specified and is required. |
403 | 403149 | Flow cannot be run | The flow parameter setting is disabled on the site preventing the flow run. |
403 | 403150 | Flow cannot be run | The flow cannot be run because flow parameters contain parameter domain type "any" but the Allow parameters that can accept any input setting is disabled on the site. |
404 | 404000 | Site not found | The site ID in the URI is unknown. |
404 | 404027 | Flow not found | The flow ID in the URI doesn't correspond to an existing flow. |
404 | 404043 | Flow parameter not found | The parameter ID specified in the request body does not match any of the existing parameters for this flow. |
405 | 405000 | Invalid request method | Request type was not POST. |
For more information, see Handling Errors.
Example
curl "http://MY-SERVER/api/3.24/sites/1edc53ac-e247-4870-9fd3-6fad0ce5f84d/flows/ d00700fe-28a0-4ece-a7af-5543ddf38a82/run?flowRunMode=incremental" -X POST -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" –d @empty-tsrequest.xml"
Content of empty-tsrequest.xml:
<tsrequest>
</tsrequest>
Example response:
<tsResponse version-and-namespace-settings>
<job id="57a8d2f6-899c-4c0f-9b25-fe0d007c5ad0" mode="Asynchronous" type="RunFlow" createdAt="2018-11-12T19:14:08Z">
<runFlowJobType flowRunId="34b9f6d3-222a-2f2f-6a22-dd2f228a6ff2">
<flow id="d00700fe-28a0-4ece-a7af-5543ddf38a82" name="SQLServerUserNamePassword Good"/>
</runFlowJobType>
</job>
</tsResponse>
Run Flow Task
Runs the specified flow run task.
Note:
- This method is unavailable if you don't have Data Management. For more information, see Tableau Prep Conductor.
- This method will fail and result in an error if your Server Administrator has disabled the RunNow setting for the site. For more information, see Tableau Server Settings(Link opens in a new window).
This method runs the scheduled task for the flow. You must first schedule the task for the flow. You can do this using the Create Schedule(Link opens in a new window) method to create the task. The Run Flow task requires you to provide a task id. To get the task-id, use the Get Flow Run Tasks method, which returns the flowRun ID. The value of the flowRun ID is what you use as the task-id.
The method adds the flow run task to the backgrounder queue. Depending upon the backgrounder load, the task might not run immediately. The method returns information about the backgrounder job responsible for running the flow run task, including a job id that can be used with the Query Job method to query the status of the flow run.
A flow task can be initiated by a REST API call, a tabcmd command, or a job calling the task on a schedule. A REST request to start a flow task will often fail if the task has been put in the task queue in any of these ways, or is already in progress. If your request results in an error code 403102
, it means that there is already a scheduled task for this within a very close time period (seconds). In this case, if the task is currently in a suspended state, it will resume.
URI
POST /api/api-version/sites/site-id/tasks/runFlow/task-id/runNow
Parameter Values
api-version | The version of the API to use, such as 3.24 . For more information, see REST API and Resource Versions. |
site-id | The ID of the site that the user is a member of. |
task-id | The ID of the flow run task that you want to run. |
Request Body
None
Permissions
Tableau Server users who are not server administrators or site administrators can only run the flow run tasks that they own.
Response Code
200
Response Body
<tsResponse >
<job id="job-id"
mode="Asynchronous"
type="RunFlow"
createdAt="Datetime-CreatedAt">
<runFlowJobType flowRunId="flow-run-id">
<flow id="flow-id" name="flow-name"/>
</runFlowJobType>
</job>
</tsResponse>
Version
Version 3.3 and later. For more information, see REST API and Resource Versions.
Errors
HTTP status | error Code |
Condition | Details |
---|---|---|---|
400 | 400084 | Flow run task error | The task specified is not a flow run task. |
For more information, see Handling Errors.
Example
curl "http://MY-SERVER/api/3.24/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/tasks/runFlow/9f8e7d6c-5b4a-3f2e-1d0c-9b8a7f6e5d4c/runNow" -X POST -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" -d @empty-tsrequest.xml
Content of empty-tsrequest.xml:
<tsrequest>
</tsrequest>
Example response:
<tsResponse version-and-namespace-settings>
<job id="50afe58f-b719-4858-8b4b-e31700685c12" mode="Asynchronous" type="RunFlow" createdAt="2018-11-12T19:43:00Z">
<runFlowJobType flowRunId="34b9f6d3-222a-2f2f-6a22-dd2f228a6ff2">
<flow id="6f4bc5a1-3905-45a7-abbc-cdb735d0b79f" name="allUseCaseTFLX"/>
</runFlowJobType>
</job>
</tsResponse>
Run Linked Task Now
Runs the specified linked task.
This method runs the specified linked task with all the steps. Depending on the setting that the task was created with, the linked task will stop at a step on failure or continue to the next step. For more information, see schedule linked tasks.
Note:
- This method is unavailable if you don't have Data Management. For more information, see Tableau Prep Conductor.
- This method will fail and result in an error if your Server Administrator has disabled the RunNow setting for the site. For more information, see Tableau Server Settings(Link opens in a new window).
URI
POST /api/api-version/sites/site-id/tasks/linked-task-id/runNow
Parameter Values
api-version | The version of the API to use, such as 3.24 . For more information, see REST API and Resource Versions. |
site-id | The ID of the site that contains the flow. |
linked-task-id | The ID of the linked task to run. |
Request Body
none
Permissions
In addition to the owner of a linked task, Tableau server administrators, site administrators, and project leaders can run linked tasks within their scope. Tableau users can run a linked task if they have permissions to run all the flows included in it.
Response Code
200
Response Body
<tsResponse>
<linkedTaskJob id="linked-task-job-id"
linkedTaskId="linked-task-id"
status="status"
createdAt="DateTime-CreatedAt"/>
</tsResponse>
Version
Version 3.15 and later. For more information, see REST API and Resource Versions.
Errors
HTTP status | error Code |
Condition | Details |
---|---|---|---|
400 | 400153 | Generic error | Unable to run the linked task for some reason other than the ones specified below. |
403 | 403155 | Linked task cannot be run | The linked task setting is disabled on the site. |
404 | 404045 | Linked task not found | The linked task ID in the URI doesn't correspond to an existing linked task. |
405 | 405000 | Invalid request method | Request type was not POST. |
409 | 409082 | Run now forbidden | Run now setting has been disabled. |
For more information, see Handling Errors.
Example
curl "http://MY-SERVER/api/3.24/sites/1edc53ac-e247-4870-9fd3-6fad0ce5f84d/tasks/linked/d00700fe-28a0-4ece-a7af-5543ddf38a82/runNow -X POST -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" –d @empty-tsrequest.xml"
Content of empty-tsrequest.xml:
<tsrequest>
</tsrequest>
Example response:
<tsResponse>
<linkedTaskJob id="765dfdfc-26ec-47ea-b53b-54419c8f6b61"
linkedTaskId="cde24429-6217-48e5-8ff5-f5dcd6a7006b"
status="InProgress"
createdAt="2022-02-15T00:22:22Z"/>
</tsResponse>
Update Flow
Updates the owner, project, of the specified flow.
URI
PUT /api/api-version/sites/site-id/flows/flow-id
Parameter Values
api-version | The version of the API to use, such as 3.24 . For more information, see REST API and Resource Versions. |
site-id | The ID of the site that contains the flow. |
task-id | The ID of the flow to update. |
Request Body
<tsRequest> <flow> <project id="6f8a2966-e173-11e8-ae74-ffd84c19d7f3"/> <owner id="711e59cf-d1c0-446e-be48-3673ae067f7b"/> </flow> </tsRequest>
Attribute Values
new-project-id | (Optional) The ID of a project to add the flow to. |
new-owner-id | (Optional) The ID of a user to assign the flow to as owner. |
Any combination of the attributes inside the <flow> element is valid. Only the attributes and child elements that are included result in updates to the flow. If no attributes or nested elements are included, no update is made.
If the <project> element is included, the id attribute must be included, and any other attributes of the <project> element are ignored.
If the <owner> element is included, the id attribute must be included, and any other attributes of the owner are ignored.
Permissions
Tableau Server users who are server administrators or site administrators can change the owner for a flow. Users who are not server administrators can move a flow from one project to another if they own the flow or the current (source) project, or are a project leader for the current project, and they have Writepermission for the destination project.
Response Code
200
Response Body
<tsResponse >
<flow id="flow-id"
name="flow-name"
description="flow-description"
webpageUrl="flow-url"
fileType="flow-file-type"
createdAt="Datetime-created"
updatedAt="Datetime-updated">
<project id="project-id" name="project-name"/>
<owner id="owner-id"/>
</flow>
</tsResponse>
The datetime-created and datetime-updated attribute values are returned in UTC format (YYYY-MM-DDTHH:MM:SSZ).
Version
Version 3.3 and later. For more information, see REST API and Resource Versions.
Errors
HTTP status | error Code |
Condition | Details |
---|---|---|---|
400 | 400000 | Bad request | The content of the request body is missing or incomplete, or contains malformed XML. |
403 | 403098 | Owner update forbidden | A non-administrator user tried to change the owner for the flow. |
403 | 403030 | Project update forbidden | A non-administrator user tried to change the project for the flow, but the caller doesn't have Write permission for the project. |
404 | 404000 | Site not found | The site ID in the URI doesn't correspond to an existing site. |
404 | 404002 | Owner not found | The owner ID in the request body doesn't correspond to an existing owner. |
404 | 404027 | Flow not found | The flow ID in the URI doesn't correspond to an existing flow. |
404 | 404005 | Project not found | The project ID in the request body doesn't correspond to an existing project. |
409 | 409041 | Flow name conflict | The flow name in the request already belongs to the specified site. For the purpose of uniqueness checks, flow names are case-insensitive. |
For more information, see Handling Errors.
Example
Example response:
<tsResponse version-and-namespace-settings>
<flow id="flow-id" name="flow-name" description="flow-description" webpageUrl="http://my-server01" fileType="tflx" createdAt="2018-11-06T04:57:55Z" updatedAt="2018-11-06T21:31:00Z">
<project id="6f8a1234-e173-456892f-ffd84c19d7f3" name="testproject"/>
<owner id="711e45tr-d1c0-554j-be48-3498ae067f7b"/>
</flow>
</tsResponse>
Update Flow Connection
Updates the server address, port, username, or password for the specified flow connection. The connection can be an input or an output connection.
URI
PUT /api/api-version/sites/site-id/flows/flow-id/connections/connection-id
Parameter Values
api-version | The version of the API to use, such as 3.24 . For more information, see REST API and Resource Versions. |
site-id | The ID of the site that contains the flow. |
flow-id | The ID of the flow to update. |
connection-id | The ID of the connection to update. To determine what connections are available for a flow, call Query Flow Connections. |
Request Body
<tsRequest>
<connection
serverAddress="server-address" serverPort="port"
userName="connection-username" password="connection-password"
embedPassword="embed-password" />
</tsRequest>
Attribute Values
server-address | The new server for the connection. |
port | The new port for the connection. |
connection-username | The new username for the connection. |
connection-password | The new password for the connection. |
embed-password | trueto embed the password; otherwise, false. |
Any combination of the attributes inside the <connection> element is valid. You will need to provide at least one attribute. If no attributes are included, this will result in an error.
Permissions
Only Tableau Server users who are server administrators or site administrators can change the connection for a flow. Users who are not server administrators can update a flow only if they have Write(save) permission for the flow and if they have write permission for the project.
Response Code
200
Response Body
<tsResponse>
<connection id="connection-id"
serverAddress="serverAddress" serverPort="port"
userName="connection-user-name" />
</tsResponse>
Version
Version 3.3 and later. For more information, see REST API and Resource Versions.
Errors
HTTP status | error Code |
Condition | Details |
---|---|---|---|
400 | 400000 | Bad request | The content of the request body is missing or incomplete, or contains malformed XML. |
403 | 403103 | Update forbidden | A non-administrator user tried to update a flow, but the caller doesn't have Write permission. |
403 | 403098 | Owner update forbidden | A non-administrator user tried to change connection information for the flow, but the caller doesn't have Write permission. |
404 | 404000 | Site not found | The site ID in the URI doesn't correspond to an existing site. |
404 | 404027 | Flow not found | The flow ID in the URI doesn't correspond to an existing flow. |
405 | 405000 | Invalid request method | Request type was not PUT. |
For more information, see Handling Errors.