Get Started Tutorial Part 2: Create a Project and Publish a Workbook to it


What is in part 2 of this tutorial?

This is Part 2 of a 3-part tutorial to help you get started using the Tableau Server REST API. Steps on this page depend on completing the previous parts. We expect this part will take you about 20 minutes to complete.

Step 1: Create a project

What are Tableau sites and projects?

A Tableau site is a grouping of your workbooks and other resources on a server. A site has its own URL and users. It is walled off from other sites on the server. A developer program sandbox is a site on the Tableau Cloud server.

A Tableau project is a way of grouping your workbooks and other resources within a site. You can organize related pieces of your work into a project and control access to those pieces by granting permissions at the project level.

To create a project on your site you'll use the site id and credentials token you copied and saved from the response to your sign in request in Part 1(Link opens in a new window) of the tutorial.

URI

Here is the model of a REST call to create a new project in a site, note that using the verb POST causes the project to be created:

POST https://MY_SERVER/api/api-version/sites/site-id/projects

The site-id is the value from your sign in response.

Request body

The request body for a call to create a project should include a name and a description of the project.

<tsRequest>
	<project
	  name="new-project-name"
	  description="This is a new project" />
</tsRequest>

Make a REST request to create a project

  • Using Postman - To use Postman to create a project:

    1. Open Postman and create a new request called Create Project and save it in your REST Tutorial Collection.
    2. Add the request body described in this section (see how it is done at Make a REST sign in request(Link opens in a new window)).
    3. Add URI with your server name and site id, and then make sure the verb is set to POST.
    4. Add the credentials token to the request header (see how it is done at Authentication of REST calls(Link opens in a new window)).
    5. Choose Send, then scroll down to view the response panel.

  • Using cURL - To use cURL to create a project:

    1. Paste your request body into a text editor such as Notepad or TextEdit and save it somewhere you will remember as a file named create-project.xml.

    2. Open a terminal window (Windows / Mac(Link opens in a new window)). At the command prompt, navigate to the directory where you saved create-project.xml. In the following command, replace:

      • MY_SERVER with the name of your server
      • api-version with the API version number of your server
      • site-id with the value of site id parameter in the sign in response
      • credentials-token with the value of the credentials token parameter of the sign in response

    3. Then run the command:

      cd /…/dir-containing-sign-in-xml
curl "https://MY_SERVER/api/api-version/sites/site-id/projects" -X POST -H "X-Tableau-Auth:credentials-token" -d "@create-project.xml"

Response Body

In Postman, you may need to scroll down to see the response body. In curl, the terminal should display the response at the prompts following your request command line.

If the response body looks like the following, then you have succeeded in creating a project on your site.

<tsResponse xmlns="http://tableau.com/api"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://tableau.com/api
  http://tableau.com/api/ts-api-3.4.xsd">
	<project id="91560c1b-a407-4453-bbf6-8368bf2367df"
	  name="new-project-name"
	  description="This is a new project"
	  createdAt="2019-05-07T22:31:58Z"
	  updatedAt="2019-05-07T22:31:58Z"
	  contentPermissions="ManagedByOwner">
		<owner id="1b526a10-048b-4d1d-96e7-e12ec7f46388"/>
		</project>
</tsResponse>

Save your project ID for use in publishing your workbook in a coming step.

If you got an error, try to use the message in the response body to figure out if there is a password, server name or other problem. Otherwise, find the error response code in the response body and try looking at the create project(Link opens in a new window) method error message list in the API reference.

You can confirm the project creation by viewing the project list on your server. You can also confirm the new project by making the REST call to list the projects on your site as follows.

Step 2: List the projects in your site

To get a list of projects on your site, try the same URI used to create a project, but using the GET verb instead of POST. You will still need to pass the credentials token in the header(Link opens in a new window).

URI

Here is the model of a REST call to list the projects in your site:

GET https://MY_SERVER/api/api-version/sites/site-id/projects

The site-id is the value from your sign in response.

Request body

None needed. Since this request is a query for a list of existing Tableau objects, you don't need to provide details in a request body. When you make a query request filter and sort(Link opens in a new window) the results to be returned.

Make a REST request to list projects in a site

  • Using Postman - To use Postman to list projects in a site:

    Here's an example of a URI to query for a listing of projects in your site in Postman:

    GET https://10ax.online.tableau.com/api/3.4/sites/c7b3099d-9e6d-44f1-8e05-d58d7fa97d4d/projects

      1. Open Postman and create a new request called Query Projects and save it in your REST Tutorial Collection.
      2. Add the URI with your server name and site id, and then make sure the verb is set to GET.
      3. Add the credentials token to the request header (see how it is done at Authentication of REST calls(Link opens in a new window)).
      4. Choose Send, then scroll down to view the response panel.

  • Using cURL - To use cURL to list projects in a site:

    Here's an example of the cURL command for the same request:

    curl "https://10ax.online.tableau.com/api/3.4/sites/c7b3099d-9e6d-44f1-8e05-d58d7fa97d4d/projects" -X GET -H "X-Tableau-Auth:RTvMkIbYT7Ww6mIMWS5UbA|FcVcVbbOdST0dedYS6pkM6mHzVL0smvT"

Response Body

In Postman, you may need to scroll down to see the response body. In curl, the terminal should display the response at the prompts following your request command line.

The response from the server listing each project in your site with their details.

<tsResponse xmlns="http://tableau.com/api"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://tableau.com/api
	http://tableau.com/api/ts-api-3.4.xsd">
	<pagination pageNumber="1" pageSize="100" totalAvailable="2"/>
	<projects>
		<project id="0ef6e0e6-b775-4d0c-8a1c-1b82e6343526"
			name="default"
			description="The default project that was automatically created by Tableau."
			createdAt="2019-05-07T17:24:16Z"
			updatedAt="2019-05-07T17:24:16Z"
			contentPermissions="ManagedByOwner">
		  <owner id="1779aa2d-0258-42ff-a476-219104ef0959"/>
        </project>
		<project id="91560c1b-a407-4453-bbf6-8368bf2367df"
			name="new-project-name" description="new-project-name"
			createdAt="2019-05-07T22:31:58Z"
			updatedAt="2019-05-07T22:31:58Z"
			contentPermissions="ManagedByOwner">
			<owner id="1b526a10-048b-4d1d-96e7-e12ec7f46388"/>
		</project>
	</projects>
</tsResponse>

Step 3: Publish a workbook

To publish a workbook, use the POST verb.

URI

Here is the model of a REST call to list publish a workbook to a site:

POST https://MY_SERVER/api/api-version/sites/site-id/workbooks

The site-id is the value from your sign in response.

Request body

The request body uses the project id you copied earlier when you made your request to create a project.

<tsRequest>
	<workbook name="test1" showTabs="true" >
		<project id="your-project-id"/>
	</workbook>
</tsRequest>

Make a REST request to publish a workbook

  • Using Postman - To use Postman to publish a workbook:

    At this time, Postman and Tableau do not play well together on a technical issue having to do with mixed content types (this kind of request combines a text part, for the REST command, and a file part, for the workbook being published). Use cURL for this tutorial. Alternatively, you can use Tableau Desktop to publish MY_WORKBOOK.twbx, or use your Tableau Developer program sandbox to create a workbook.

  • Using cURL - To use cURL to publish a workbook:

    As in previous steps, to use cURL to publish a workbook to your project, create an xml file called publish-workbook.xml containing the request body in this section.

    curl "https://MY_SERVER/api/3.4/sites/site-id/workbooks" -X POST -H "X-Tableau-Auth:credentials token" -H "Content-Type: multipart/mixed;" -F "request_payload=@publish-workbook.xml" -F "tableau_workbook=@MY_WORKBOOK.twbx"

Response Body

In Postman, you may need to scroll down to see the response body. In curl, the terminal should display the response at the prompts following your request command line.

A successful response from the server will list the details of each workbook in your site. These contain the project(s) the workbook is included in.

<tsResponse xmlns="http://tableau.com/api"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://tableau.com/api
	http://tableau.com/api/ts-api-3.4.xsd">
	<workbook id="0d110ecf-b4d8-42c0-af2b-756be5677eeb"
		name="new-workbook"
		contentUrl="new-workbook"
		. . . other workbook attributes>
		<project id="91560c1b-a407-4453-bbf6-8368bf2367df"
		name="new-project-name"/>
		<owner id="1b526a10-048b-4d1d-96e7-e12ec7f46388"/>
		<tags/>
		<views>
			<view id="6305e2d7-0d86-4d2d-a45b-4811ab13cddd"
				name="Sheet 1"
				contentUrl="new-workbook/sheets/Sheet1"
				createdAt="2019-05-09T19:23:09Z"
				updatedAt="2019-05-09T19:23:09Z">
				<tags/>
			</view>
		</views>
		<dataAccelerationConfig accelerationEnabled="false"/>
	</workbook>
</tsResponse>

Save the workbook ID for a coming tutorial step that gives users permissions to use the workbook.

Next Up: Part 3: Make a User Group and Give it Permissions (~20 minutes)


Back to top
Thanks for your feedback!Your feedback has been successfully submitted. Thank you!