Customize Labels
Starting in Tableau Cloud June 2023, if you have a Data Management license and are an administrator, you can use the REST API to customize the label values that are built into Tableau. You can also create new, custom label values. These customizations affect the way that labels appear throughout Tableau when users interact with labels.
Note: You can't customize or create label values in current releases of Tableau Server.
For details on the REST API methods you use to customize and create label values, see the Tableau REST API Reference, specifically the following metadata methods:
- Get labelValue(Link opens in a new window)
- List labelValues on Site(Link opens in a new window)
- Create or Update labelValue(Link opens in a new window)
- Update labelValue(Link opens in a new window)
- Delete labelValue(Link opens in a new window)
The Tableau REST API Postman Collection(Link opens in a new window) contains an open source collection of these methods (and others) for easy learning, development, and testing.
What is a label value?
A "label value" is one of the properties of a data label on an asset (along with other properties, such as owner and message). This label value has properties of its own, including name, category, and description. The label value and its properties determine the options and appearance of the label dialog when users are working with labels on an asset.
Data label value properties
Label values have the following properties: Name, category, and description.
Name
The label value name appears in the dropdown menu when a user is selecting a label to apply. For example, here the label value name "Under maintenance" is selected in the Data Quality Warning dialog.
The label value name is customizable, except for certification labels and the monitoring warnings.
Category
The label value category affects where and how the label appears, whether it appears on assets that are downstream from the one it's attached to, and which parts are customizable, among other things. You can't change or customize a label value's category. The categories built into Tableau are certification, warning, and sensitivity.
Description
The label value description appears under the dropdown menu, and helps the user understand what the label is used for. For example, the label value description in this Data Quality Warning dialog says "This asset is no longer maintained and shouldn't be used."
There are default descriptions for all built-in labels values. An administrator can customize them to suit the organization's needs.
Other important label concepts
Visibility
The label visibility determines the appearance of the label. High visibility labels appear in more places and may appear more urgent to the user. When a label has a category of warning, users with permissions can override the visibility on a per-asset basis.
Built-in label values vs custom label values
A built-in label value is one that comes built into Tableau. Examples include certification, the maintenance data quality warning, and any other label values not created by an administrator.
A custom label value is one that the administrator creates to suit the needs of the organization. Each custom label value, like the existing built-in label values, has a name, a category, and a description. The category of a custom label value must be either warning or sensitivity. After it's created, a custom label value appears in label selection dropdown menus the same way that built-in label values do.
Internal labels
The data quality warnings that arise from extract refresh monitoring and flow run monitoring are internal labels. Only the system can add or remove internal labels. They are triggered by a job's success or failure, and can't be added to or removed from an asset by users.
Limitations to customization
Length limitations
- The recommended maximum length for a label value name is 24 characters.
- The recommended maximum length for a label value description is 500 characters.
Category limitations
Not all built-in labels can be customized, and not all categories allow custom label values. The certification category, for instance, allows only the built-in label value, and that label value can't be customized. The table below lists, by category, the editability of label value properties and the ability to create new labels:
| Label value category | Allows administrator to edit label values | Allows administrator to edit label descriptions | Allows administrator to create new labels |
| Certification | No | Yes | No |
| Warning | Yes* | Yes* | Yes |
| Sensitivity | Yes | Yes | Yes |
*Monitoring warnings (flow run monitoring and extract refresh monitoring) can't be customized.
Scenarios for customization
Scenario: Customize a built-in label value
Suppose you decide that the data quality warning called "Warning" could be more specific. As an administrator, you change the label value name from the default ("Warning") to something you think is more useful to your organization: "Not approved". The label value name "Not approved" now appears in the label dialog when users are selecting labels.
Alternatively, you could change the label value description so that the user learns more about the warning in the label dialog. For example: "This asset doesn't meet quality standards required by the ABC department."
Scenario: Create a custom label value
Suppose you want users to have more granular control over classifying the sensitivity of assets. You create two new sensitivity label values with the names "Public" and "PII". The custom label value names "Public" and "PII" now appear in the label dialog dropdown and description, alongside the built-in sensitivity label value.