User Functions

Applies to: Tableau Cloud, Tableau Desktop, Tableau Public, Tableau Server

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 visualizations published to Tableau Server or Tableau Cloud, so that only certain people can see your visualization.

For example, if you have a visualization 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 visualization.

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 customize 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 attribute functions can't be used in non-embedding workflows or with OIDC or SAML protocols.

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: Tableau Cloud and Tableau Server: the full name of the signed-in user Tableau Desktop: the local or network full name for the user User filters When used as a filter, a calculated field such as `[Username field] = FULLNAME( )` can be used to create a user filter that only shows data that is relevant to the person signed in to the server.

ISFULLNAME

Syntax	`ISFULLNAME("User Full Name")`
Output	Boolean
Definition	Returns `TRUE` if the current user's full name matches the specified full name or `FALSE` if it does not match.
Example	ISFULLNAME("Hamlin Myrer")
Notes	The `<"User Full Name">` argument must be a literal string, not a field. This function checks: Tableau Cloud and Tableau Server: the full name of the signed-in user Tableau Desktop: the local or network full name for the user

ISMEMBEROF

Syntax	`ISMEMBEROF("Group Name")`
Output	Boolean or null
Definition	Returns `TRUE` if the person currently using Tableau is a member of a group that matches the given string, `FALSE` if they're not a member, and `NULL` if they're not signed in.
Example	ISMEMBEROF('Superstars') ISMEMBEROF('domain.lan\Sales')
Notes	The `<"Group Full Name">` argument must be a literal string, not a field. 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 `ISMEMBEROF( )` function will also accept Active Directory domains. The Active Directory domain must be declared in the calculation with the group name. 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 `<"username">` argument must be a literal string, not a field. This function checks: Tableau Cloud and Tableau Server: the username of the signed-in user Tableau Desktop: the local or network username for the user

USERDOMAIN( )

Syntax	`USERDOMAIN( )`
Output	String
Definition	Returns the domain for the current user .
Notes	This function checks: Tableau Cloud and Tableau Server: the user domain of the signed-in user Tableau Desktop: the local domain if the user is on a domain

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: Tableau Cloud and Tableau Server: the username of the signed-in user Tableau Desktop: the local or network username for the user User filters When used as a filter, a calculated field such as `[Username field] = USERNAME( )` can be used to create a user filter that only shows data that is relevant to the person signed in to the server.

USERATTRIBUTE

Note: Before you use this function, see For embedding workflows in Tableau Cloud only. For more information, see Authentication and Embedded Views(Link opens in a new window) in the Embedding API v3.

Syntax	`USERATTRIBUTE('attribute_name')`
Output	String or null
Definition	If `<'attribute_name'>` is part of the JSON web token (JWT) passed to Tableau, the calculation returns the first value of `<'attribute_name'>`. Returns null if `<'attribute_name'>` does not exist.
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 visualization 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 visualization, 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

Syntax	`USERATTRIBUTEINCLUDES('attribute_name', 'expected_value')`
Output	Boolean
Definition	Returns `TRUE` if both of the following are true: `<'attribute_name'>` is part of the JSON web token (JWT) passed to Tableau one of `<'attribute_name'>` values equals `<'expected_value'>` . Returns `FALSE` otherwise.
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 visualization 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 visualization, Tableau checks if the Region user attribute matches one of [Region] field values. When true, the visualization shows the appropriate data. When User3 from the North region accesses the same visualization, 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 visualization:

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 visualization

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 Color on the Marks card.
On the Columns shelf, select the Longitude field and hold down Control (Comman 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 Color on the Marks card.

The map view on the right updates with new colors.
On the Marks card, click the mark type drop-down and select Map.
On the Marks card, click Color, and, under Opacity, adjust the slider to 50%.
On the Marks card, click the first Longitude tab.
On the Marks card, click Color > Edit Colors, and then select Gray from the color 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 visualizations.

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 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 behavior 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 visualization.

Tableau Desktop and Web Authoring Help