User Functions
This article introduces user functions and their uses in Tableau. It also demonstrates how to create a user calculation using an example.
Why use user functions
User functions can be used to create user filters or row-level security filters that affect visualisations published to Tableau Server or Tableau Cloud so that only certain people can see your visualisation.
For example, if you have a visualisation that shows the sales performance for each employee in your department published on Tableau Server or Tableau Cloud, you might want to only allow employees to see their own sales numbers when they access that visualisation.
In this case, you can use the ISMEMBEROF function to create a field that returns true if the username of the person signed in to the server is a member of a specified group (on the server), such as the "Managers" group, for example. Then when you filter the view using this calculated field, only a person who is part of that group can see the data.
The calculation in this case might look something like the following:
ISMEMBEROF('Managers')Note: If your group or user names contain certain non-alphanumeric you must use HTML URL Encoding for the special characters when using the functions below.
Some special characters are permitted without HTML URL encoding, such as underscores, parentheses and exclamation points. _ ( ) ! Many other characters must be encoded.
For example, the function ISMEMBEROF("USERS+") needs to be written as ISMEMBEROF("USERS%2B"), because the '%2B' is the HTML URL Encoding for the '+' symbol. For information on HTML URL encoding, please see HTML URL Encoding Reference(Link opens in a new window) at the W3schools Web Developer site.
For embedding workflows in Tableau Cloud only
Among the user functions, a subset of user attribute functions can be used with Tableau connected apps(Link opens in a new window). The user attribute functions (USERATTRIBUTE and USERATTRIBUTEINCLUDES) allow user attributes to be captured by Tableau at runtime as part of the authentication workflow. When user attributes are passed from JSON Web Tokens (JWTs), embedded content authored with these functions can control and customise data displayed to users.
Notes:
Check the Embedding API v3(Link opens in a new window) Help for known issues that might affect your workflow.
User attribute functions can be included in content authored in Tableau Desktop or Tableau Cloud.
- Preview of the content with these functions is not available when authoring in Tableau Desktop or Tableau Cloud. User attribute functions will return NULL or FALSE values. To ensure user attribute functions work as expected, we recommend you review the content after embedding in your external application. For more information about embedding workflows that include these user functions, see the Embedding API v3(Link opens in a new window) Help.
User functions available in Tableau
FULLNAME( )
| Syntax | FULLNAME( ) |
| Output | String |
| Definition | Returns the full name for the current user. |
| Example | FULLNAME( ) This returns the full name of the signed-in user, such as "Hamlin Myrer". [Manager] = FULLNAME( ) If manager "Hamlin Myrer" is signed in, this example returns TRUE only if the Manager field in the view contains "Hamlin Myrer". |
| Notes | This function checks:
User filters When used as a filter, a calculated field such as |
ISFULLNAME
| Syntax | ISFULLNAME("User Full Name") |
| Output | Boolean |
| Definition | Returns |
| Example | ISFULLNAME("Hamlin Myrer") |
| Notes | The This function checks:
|
ISMEMBEROF
| Syntax | ISMEMBEROF("Group Name") |
| Output | Boolean or null |
| Definition | Returns |
| Example | ISMEMBEROF('Superstars')ISMEMBEROF('domain.lan\Sales') |
| Notes | The If the user is signed in to Tableau Cloud or Tableau Server, group membership is determined by Tableau groups. The function will return TRUE if the given string is "All Users" The If a change is made to a user's group membership, the change in the data that is based on the group membership is reflected in a workbook or view with a new session. The existing session will reflect stale data. |
ISUSERNAME
| Syntax | ISUSERNAME("username") |
| Output | Boolean |
| Definition | Returns TRUE if the current user's username matches the specified username or FALSE if it does not match. |
| Example | ISUSERNAME("hmyrer") |
| Notes | The This function checks:
|
USERDOMAIN( )
| Syntax | USERDOMAIN( ) |
| Output | String |
| Definition | Returns the domain for the current user. |
| Notes | This function checks:
|
USERNAME( )
| Syntax | USERNAME( ) |
| Output | String |
| Definition | Returns the username for the current user. |
| Example | USERNAME( ) This returns the username of the signed-in user, such as "hmyrer". [Manager] = USERNAME( ) If manager "hmyrer" is signed in, this example returns TRUE only if the Manager field in the view contains "hmyrer". |
| Notes | This function checks:
User filters When used as a filter, a calculated field such as |
USERATTRIBUTE
Note: For embedding workflows in Tableau Cloud only. For more information, see Authentication and Embedded Views(Link opens in a new window).
| Syntax | USERATTRIBUTE('attribute_name') |
| Output | String or null |
| Definition | If Returns null if |
| Example | Suppose "Region" is the user attribute included in the JWT and passed to Tableau (using the connected app already configured by your site admin). As the workbook author, you can set up your visualisation to filter data based on a specified region. In that filter, you can reference the following calculation. [Region] = USERATTRIBUTE("Region")When User2 from the West region views the embedded visualisation, Tableau shows the appropriate data for the West region only. |
| Notes | You can use the USERATTRIBUTEINCLUDES function if you expect <'attribute_name'> to return multiple values. |
USERATTRIBUTEINCLUDES
Note: For embedding workflows in Tableau Cloud only. For more information, see Authentication and Embedded Views(Link opens in a new window).
| Syntax | USERATTRIBUTEINCLUDES('attribute_name', 'expected_value') |
| Output | Boolean |
| Definition | Returns
Returns |
| Example | Suppose "Region" is the user attribute included in the JWT and passed to Tableau (using the connected app already configured by your site admin). As the workbook author, you can set up your visualisation to filter data based on a specified region. In that filter, you can reference the following calculation. USERATTRIBUTEINCLUDES('Region', [Region])If User2 from the West region accesses the embedded visualisation, Tableau checks if the Region user attribute matches one of [Region] field values. When true, the visualisation shows the appropriate data. When User3 from the North region accesses the same visualisation, she’s unable to see any data because there’s no match with [Region] field values. |
Create a user calculation
User calculations work directly with the users and groups you have set up on Tableau Server or Tableau Cloud. You can create user calculations to use as filters so users only see the data that is relevant to them.
For example, if you have a map viz similar to the following, which shows sales data for 48 US states, you can create a user calculation to show only parts of the map that are relevant to each user, such as data relevant for a regional manager versus a national manager. (A national manager should be able to see data for the entire country, while a regional manager should only be able to see data for the region they manage).
When the national manger is signed in, they see the following visualisation:
When the western regional manager is signed in, they see only sales for their region:
To create a user function that performs similarly to this example, follow the steps below.
Before you begin
To follow along with this example, you must have access to Tableau Server or Tableau Cloud. You must also be a Server or Site Administrator.
Step 1: Create the users and groups
Sign in to Tableau Server or Tableau Cloud.
In Tableau Server or Tableau Cloud, add the following users:
Sadie Pawthorne
Chuck Magee
Fred Suzuki
Roxanne Rodriguez
For more information, see Add Users to a Site(Link opens in a new window) in the Tableau Server Help.
Create a new group called National Managers.
For more information, see Create a Local Group(Link opens in a new window) in the Tableau Server Help.
Add yourself to the National Managers group.
For more information, see Add Users to a Group(Link opens in a new window) in the Tableau Server Help.
Step 2: Create the visualisation
Open Tableau Desktop, and connect to the Sample-Superstore data source, which comes with Tableau.
In the bottom left corner of the workspace, click the Data Source tab.
On the Data Source page, from the Connections pane on the left, drag the People sheet to the join area.
Click the join icon and select Left.
Navigate to a new worksheet.
In the Data pane, under Dimensions, double-click State.
A map view is created.
From the Data pane, under Measures, drag Sales to Colour on the Marks card.
On the Columns shelf, select the Longitude field and hold down Control (Command on Mac) on your keyboard to copy it. Drag the copy to the right of the original on the Columns shelf.
On the Marks card, click the second (bottom) Longitude tab.
From the Data pane, drag Region to Colour on the Marks card.
The map view on the right updates with new colours.
On the Marks card, click the mark type drop-down and select Map.
On the Marks card, click Colour, and, under Opacity, adjust the slider to 50%.
On the Marks card, click the first Longitude tab.
On the Marks card, click Colour > Edit Colours, and then select Grey from the colour palette drop-down list.
The map view on the left updates.
On the Columns shelf, right-click the Longitude field on the right and select Dual Axis.
The map looks like the following:
Step 3: Create the User Calculation
Select Analysis > Create Calculated Field.
In the calculation editor that opens, do the following:
Name the calculated field, User Filter.
Enter the following formula:
[Regional Manager] = USERNAME() OR ISMEMBEROF("National Managers")This calculation checks if a person is included in the Region (People) field, or if a person is included in the National Managers group. If so, it returns true.
When finished, click OK.
The new user calculation appears under Dimensions in the Data pane. Just like your other fields, you can use it in one or more visualisations.
Step 4: Add the user calculation to the Filters shelf
From the Data pane, under Dimensions, drag User Filter to the Filters shelf.
In the Filter dialog box that opens, select True, and then click OK.
Note: If you are not signed in to Tableau Server or Tableau Cloud, the True option is not visible. In Tableau Desktop, sign in to Tableau Server or Tableau Cloud to select it. See Sign in to Tableau Server or Tableau Cloud(Link opens in a new window) for more information.
Step 5: Test the calculation
In Tableau Desktop, in the bottom-right corner of the workspace, click on the Filter as User drop-down and change the user to Sadie Pawthorne.
The map updates to show only the West region of the United States because Sadie is assigned to the West region in the People sheet.
Select the Filter as User drop-down again and change the user to Roxanne Rodriguez.
The map updates to show only the Central region of the United States because Roxanne is assigned to the Central region in the People sheet.
Select the Filter as User drop-down again and change the user to Chuck Magee.
The map updates to show only the East region of the United States because Chuck is assigned to the East region in the People sheet.
Select the Filter as User drop-down again and change the user to Fred Suzuki.
The map updates to show only the South region of the United States because Fred is assigned to the South region in the People sheet.
Select the Filter as User drop-down one more time and change the user back to yourself.
The map updates to show all data because you are a part of the National Managers group on the server.
This behaviour persists when you publish the view to Tableau Server or Tableau Cloud. Users not listed in the National Managers group, or in the People sheet in the Sample Superstore data source see only a blank visualisation.