Embed New Empty Workbook on Tableau


In some situations, you might have a need to embed a Tableau workbook in your web site that is blank (empty) and not connected to any data source. Users to your site could then choose the data source(s), and create new worksheets and dashboards to explore that data. In other cases, you might want to embed a workbook that is already connected to a data source, but is otherwise blank or empty. You can handle both of these situations using the Embedding API 3.6.0 library (or later) and Tableau 2023.2 (or later). In either case, the user will need to have authoring permissions on Tableau.

To embed an empty workbook, you first create a TableauAuthoringViz object or <tableau-authoring-viz> web component. You construct a URL as the src in one of two ways, depending upon whether you are connecting to a data source, or just embedding an empty workbook without a data source.

In this section

Empty workbook without a data source

The URL to create the new empty workbook without a data source you use the keyword newWorkbook in the URL, along with the path to the Tableau Cloud or Tableau Server, the name of the site, and a 32-bit GUID (UUID). The GUID must be unique for each instance. The URL uses the following syntax:

https://SERVER-NAME/t/SITE-NAME/newWorkbook/GUID

For example, the following URL creates a new empty workbook on the Tableau Server (https://example.com) and on the site (outta-site).

https:/example.com/t/outta-site/newWorkbook/30d5f141-168d-4d88-8050-5f25e30fd164

You add the URL to the web component as the src attribute.


<tableau-authoring-viz id="tableauAuthViz"
    src="https:/example.com/t/outta-site/newWorkbook/30d5f141-168d-4d88-8050-5f25e30fd164">
</tableau-authoring-viz>

Note: If you use a URL to open an empty workbook without a data source, and you are using a connected app for authentication, the session could crash. For more information, see Known Issues.

Empty workbook with a data source

The URL to create the new empty workbook that is connected to a data source you use the keyword authoringNewWorkbook in the URL, along with the path to Tableau Cloud or Tableau Server, the name of the site, a 32-bit GUID (UUID), and the name of the data source. The GUID must be unique for each instance. For the name of the data source, use the name of a published data source on Tableau Cloud or Tableau Server. You can find the data source name by using the Tableau REST API Query Data Sources method. The name of the data source is returned in the response as the contentUrl attribute.

The URL for an empty workbook connected to a data source uses the following syntax:

https://SERVER-NAME/t/SITE-NAME/authoringNewWorkbook/GUID/DATASOURCE-NAME

For example, the following URL creates a new empty workbook on the Tableau (https://example.com) and on the site (outta-site). The name of the published data source is SuperstoreDatabase.

https:/example.com/t/outta-site/authoringNewWorkbook/2c15f16c-b708-4f44-bc32-14ff931703f6/SuperstoreDatasource

You add the URL to the <tableau-authoring-viz web component as the src attribute.


<tableau-authoring-viz id="tableauAuthViz"
    src="https:/example.com/t/outta-site/authoringNewWorkbook/2c15f16c-b708-4f44-bc32-14ff931703f6/SuperstoreDatasource">
</tableau-authoring-viz>

Note: Be sure to use the data source name specified in the contentUrl attribute that is returned from the Tableau REST API Query Data Sources method. This data source name might not exactly match the name you see when you click Explore > All Data Sources in Tableau. For example, the name of the published data source in the previous example, appears as Superstore Datasource on Tableau Cloud, and as SuperstoreDatabase in the contentUrl returned from the Tableau REST API query. Use the name as shown in the contentUrl attribute.

Example: embedding an empty workbook

When you use either of the empty workbook scenarios, the GUID/UUID you specify must be unique for each instance. For example, you could append a new GUID to the src URL each time the page is loaded, using a function that returns a new GUID. The following code shows a simple way of doing this using your Tableau Cloud Developer site or Sandbox (on https://10ax.online.tableau.com). Replace YOUR-SITE with the name of your Sandbox site.

Note if you are not using the Tableau Cloud Developer site, replace 10ax with the name of your Tableau Cloud pod in the URLs for the library and the viz.

This example opens an empty workbook that is not connected to a data source. To connect to a data source, you would replace newWorkbook with authoringNewWorkbook and then append the name of the data source to the URL.


<!DOCTYPE html>
<html>
<head>
  <title>Simple Empty Workbook</title>
  <script type="module" >

  import {
    TableauAuthoringViz,
    TableauEventType,
  } from 'https://10ax.online.tableau.com/javascripts/api/tableau.embedding.3.latest.min.js';

    const viz = new TableauAuthoringViz();   // create the authoring viz object

    // construct unique GUID for URL
    const guid = crypto.randomUUID();
    console.log(`The UUID is: ${guid}`);
    let url=`https://10ax.online.tableau.com/t/YOUR-SITE/newWorkbook/${guid}`;
    console.log(url);

    viz.src = url;
    viz.height = "600";
    viz.width = "800";

    // add viz to HTML code
    document.getElementById('new-workbook').appendChild(viz);


  </script>
</head>
<body>
  <h2>This is an empty workbook</h2>
    <div id="new-workbook"></div>
</body>
</html>