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( )

SyntaxFULLNAME( )
OutputString
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

SyntaxISFULLNAME("User Full Name")
OutputBoolean
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

SyntaxISMEMBEROF("Group Name")
OutputBoolean 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

SyntaxISUSERNAME("username")
OutputBoolean
DefinitionReturns 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( )

SyntaxUSERDOMAIN( )
OutputString
DefinitionReturns 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( )

SyntaxUSERNAME( )
OutputString
DefinitionReturns 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: For embedding workflows in Tableau Cloud only. For more information, see Authentication and Embedded Views(Link opens in a new window).

SyntaxUSERATTRIBUTE('attribute_name')
OutputString 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 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.

NotesYou 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).

SyntaxUSERATTRIBUTEINCLUDES('attribute_name', 'expected_value')
OutputBoolean
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 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

  1. Sign in to Tableau Server or Tableau Cloud.

  2. 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.

  3. 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.

  4. 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

  1. Open Tableau Desktop, and connect to the Sample-Superstore data source, which comes with Tableau.

  2. In the bottom left corner of the workspace, click the Data Source tab.

  3. On the Data Source page, from the Connections pane on the left, drag the People sheet to the join area.

  4. Click the join icon and select Left.

  5. Navigate to a new worksheet.

  6. In the Data pane, under Dimensions, double-click State.

    A map view is created.

  7. From the Data pane, under Measures, drag Sales to Colour on the Marks card.

  8. 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.

  9. On the Marks card, click the second (bottom) Longitude tab.

  10. From the Data pane, drag Region to Colour on the Marks card.

    The map view on the right updates with new colours.

  11. On the Marks card, click the mark type drop-down and select Map.

  12. On the Marks card, click Colour, and, under Opacity, adjust the slider to 50%.

  13. On the Marks card, click the first Longitude tab.

  14. 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.

  15. 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

  1. Select Analysis > Create Calculated Field.

  2. 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

  1. From the Data pane, under Dimensions, drag User Filter to the Filters shelf.

  2. 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

  1. 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.

  2. 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.

  3. 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.

  4. 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.

  5. 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.

See Also

Functions in Tableau

Tableau Functions (by Category)

Tableau Functions (Alphabetical)

Thanks for your feedback!Your feedback has been successfully submitted. Thank you!