Tableau Desktop and Web Authoring Help

As a content creator, it's important to understand how updates you make to workbooks and data sources can impact the end user. Custom views are a popular way to personalize how vizzes are consumed, but custom views can break if their source content changes. Avoid making changes known to impact custom views, if possible. When changes need to be made, follow the steps outlined later in this topic.

In general, there are some best practices when working with content known to use custom views.

• Advise end users to only create custom views on stable content.
  • Use projects or naming systems to identify workbooks that are being modified and recommend users don't create custom views on them.
• Test changes in a staging or development environment. Test custom views that are representative of the expected filters, user actions, parameter settings, and other customizations.
• Proactively notify users before publishing changes that may break custom views. (Retrieve a list of all custom views applied to a workbook using the custom views methods in Tableau's REST API(Link opens in a new window).)

Changes known to impact custom views

While it's best to test any changes to verify their impact on custom views, there are some updates that are known to impact custom views.

This list isn't comprehensive and is intended for guidance only.

Workbook changes

• Name changes. Changing the name of the workbook (or the sheet the custom view is associated with) breaks the custom views.
• Parameters. Adding or removing a parameter may cause a custom view to break or fail to update as expected.
  • If a parameter is added to the original content, the custom view may break.
  • If a parameter control is removed, calculated fields that used its input retain their last value and are no longer adjustable.
• Filters. Removing a filter removes the filter control but leaves the data in a filtered state.
  • In general, if a filter is deleted in the original content, a custom view that used that filter continues to work. However, the data remains filtered with no filter control present. This means users can't change the filter selection from the custom view.
  • Changing the filter control from slider to relative date doesn't adjust the filter to accurately reflect the relative date as expected.
  • If custom views are used to control filter selections, consider using embedding filter parameters in a shared URL instead.
• Hiding sheets. Setting a sheet to hidden, even if it's later unhidden, breaks custom views on that sheet.
• Republishing. Deleting and republishing a workbook breaks its custom views.

Data source changes

• Data source changes. Replacing a data source using the Replace data source functionality or replacing an embedded data source with a published copy of the same data source breaks the custom views.
• Data type. Changing the data type of a field relevant to the custom view breaks the custom view.
• Removing fields. Removing fields, calculations, groups, or sets that custom views are based on breaks the custom view.

Update content safely

The following is a set of best practices to minimize the risk of breaking existing custom views.

• Edit the workbooks and changes to the data sources separately.
• Don't republish a workbook that has a replaced data source.
• Edit a local version of the workbook or data source and republish it with the same name.

Modify a workbook

These steps assume the workbook uses a live connection to a separately published data source and has existing custom views.

Modify a workbook with web editing

Web editing is the preferred method for modifying a workbook. Only use Tableau Desktop if necessary.

1. Edit a workbook in the browser, avoiding the items addressed earlier that are known to break custom views.
   • If changes need to be made to the data, don't make them now. See the section on modifying a data source.
2. Publish the workbook to the same location with the same name, saving over the existing version.

Modify a workbook with Tableau Desktop

When possible, modify workbooks in the browser. Only use Tableau Desktop if necessary.

1. Open a local version of the workbook (download the workbook first if necessary).
2. Edit the workbook, avoiding the items addressed earlier that are known to break custom views.
   • If changes need to be made to the data, don't make them now. See the section on modifying a data source.
3. Publish the workbook to the same location with the same name, replacing the existing version.
   • Don't check the option to "Update the workbook to use the published data source".

Modify a data source

1. Open a local version of the data source in Tableau Desktop by downloading the workbook and creating a local copy of the data source:
   1. Download the workbook and open it in Tableau Desktop.
   2. Right-click the data source and select "Create Local Copy".
   3. Right-click the new data source and select "Replace Data Source…"
   4. Swap the existing connection to the published data source with the newly created local copy.

   Note: Using a local version in a workbook is the preferred method because it allows you to verify data source changes directly in the workbook. Alternatively, you can download the data source or use a locally stored copy.

2. Edit to the data source, avoiding the items addressed earlier that are known to break custom views.
3. Publish the data source.
   1. Use the same name and save over the existing data source.
   2. Don't check the option to "Update the workbook to use the published data source".
   3. Don't publish the workbook with the modified data source. If changes need to be made to the workbook contents, see the section on modifying workbooks.

Investigate broken custom views

Note: This section assumes familiarity with XML and basic command-line interactions.

In a .twb workbook file, the XML of a workbook contains identifying tags for elements of the workbook. When a custom view is created, a snapshot is taken of the interactive elements (such as filter or set values, parameters, or selected marks) and their values. When a custom view is accessed, Tableau applies the attribute values stored with the custom view to the relevant element IDs. If the element IDs are changed or the attribute values can't be loaded, the custom view breaks.

It may be possible to identify what changed to break a custom view by comparing a .twb from before and after the change.

1. You need a .twb of the workbook when the custom view is functioning (save a copy of content before making any changes).
2. In another copy of the workbook, make the change thought to cause the custom view to break and save it as a different .twb.
3. In the command line, run the following command (substituting the files from step one as file1.twb and from step two as file2.twb).

   vdmdiff file1.twb file2.twb

4. The results highlight changes between the files.

Some IDs or attribute values (in [brackets]) that are known to break custom views if changed:

<datasources>
	<datasource name='[ID]'>

<worksheets>
	<worksheet name='[ID]'>
<table>
<view>
<datasource-dependencies datasource='[ID]'>
<column datatype='[Value]' name='[Value]'>

<dashboards>
	<dashboard name='[ID]'>