Tableau Server on Linux Help

Use a data policy to apply row-level security to one or more tables in a virtual connection. A data policy filters the data, ensuring that users see only the data they're supposed to see. Data policies apply to both live and extract connections.

About data policies

A data policy has three main components:

1. The tables they apply to are called policy tables. These are the tables that are filtered.
2. The mapped columns that define the relationships between tables (for example, between entitlement and fact tables) and between table columns and policy columns. A policy column is the column used to filter data.
3. The policy condition, which is an expression or calculation that is evaluated for every row at query time. If the policy condition is TRUE, the row is shown in the query.

When you create a data policy, you need a column you can use to filter the data. This column is called a policy column. Data is filtered by the policy condition, usually using a user function, such as USERNAME() or FULLNAME().

If your policy table includes a column that you can filter on, then use that column as your policy column.

When a policy table doesn't include such a column, use an entitlement table with a column you can use to filter the data. An entitlement table is a table that includes both a policy column you can use to filter policy tables and another column you can relate (map) to a column in a policy table (as shown in the data policy example image above).

Filter with a policy column from a policy table

The most common way to filter data is to use a column in the table that has the data that you want to filter on. Use that column as a policy column and then map the appropriate table columns to the policy column.

To use a policy column to filter your data, first, add tables to the policy from the left pane. To add a table, do one of the following:

• Double-click on the table name.
• Click the drop-down arrow near the table name and select Manage table with policy.
• Or, drag the table to the right and drop it on Add as Policy Table.

After a table is added to a policy, a shield icon appears to the right of the table name in the left pane indicating that it's a policy table.

Next, map columns to create a relationship between the column name in the table and the policy column name. Use the policy column name in the data policy condition to control row-level data access for users:

1. Click +Add Column to Map to add one or more columns you’ll use to filter data.
2. Name the policy column. You'll use this name in the policy condition.
3. For each table the policy applies to, use the drop-down menu to select the table column that maps to the policy column.
4. Repeat this process for as many policy columns as you want to use in the policy condition.

Tip: Instead of using the +Add Column to Map button, you can start typing the calculation in the policy condition area and use auto-complete to choose the column name, which will then populate the policy column information under Step 1.

An example using a policy column from a policy table

1. The Sales table has a [Salesperson] column, and the Region table has a [SalesRep] column. The Salesperson and SalesRep data matches the full name of Tableau users on your site.
2. You want to filter the Sales and Region data by Salesperson, so you name the policy column "Salesperson", and then map the Salesperson column from Sales and the SalesRep column from Region to the Salesperson policy column.
3. Then write the policy condition to filter both tables. Use the [Salesperson] policy column and the FULLNAME() user function so that each user can see only their own data.

Filter with policy column from an entitlement table

Entitlement tables are used when your policy table doesn’t contain a column you can filter on. You can use the entitlement table to map a column in the data table to a column in the entitlement table. Note the following:

• Be sure to include the entitlement table as a table in the virtual connection. You can use a table from any connection or database as a central entitlement table that secures tables across many other databases. In some cases, an entitlement table that’s in the same database as the tables you’re securing can be a potential security risk because of the potential for exposing employee data. And having an entitlement table in a different database can make it easier to control permissions, for example, to grant someone access to a database.
• If you don't want virtual connection users to see the entitlement table, you can toggle the setting in the Visibility column on the Tables tab to hide it. Once hidden, the entitlement table is still available for policy filtering but can’t be used in vizzes or workbook data sources.

Note: Connecting directly to a flow output (.hyper file) is not supported for the entitlement table. The flow output must write directly to the database.

To use an entitlement table to filter your data:

1. Add the data tables that you want the data policy to apply to. Do one of the following:
   • Double-click on the table name.
   • Click the drop-down arrow near the table name and select Manage table with policy.
   • Or, drag the table to the right and drop it on Add as Policy Table.
2. After a table is added to a policy, a shield icon appears to the right of the table name in the left pane indicating that it's a policy table.
3. Select the entitlement table, then either:
   • Click the drop-down arrow and select Use as entitlement table.
   • Or, drag the table to the right and drop it on Add as Entitlement Table.
4. For each table that the policy applies to, click the drop-down menu and select the column to map the policy table to the entitlement table.

An example using a policy column from an entitlement table

1. The data you want to filter has an EMP_ID column, but not an employee name column. However, you have a second table that includes columns for both EMP_ID and the employee's FULL NAME. And, the values in the employee FULL NAME column match the full name of Tableau users on your site.
2. You can add Employees table to the policy as an entitlement table, and then map the policy table column name EMP_ID to the entitlement column name EMP_ID for each table.
3. Then use the FULLNAME() function in your policy condition to match the Tableau Server user's full name with the entitlement table's [FULL NAME] column (which is the policy column) so that each user can see only their own data.

Write a policy condition

The last step in creating a data policy is to write a policy condition, which is a calculation or expression used to define row-level access. Policy conditions are often used to limit access to users or groups through user functions.

A policy condition:

• Is required in a data policy.
• Must evaluate to true or false.
• Shows rows when the policy condition is true.

When you close a policy tab, it doesn't discard your work.

Policy condition examples

Shows only rows where the Region column value is North:

[Region] = "North"

Enables a signed-in user to see the rows where the user's name matches the value in EmployeeName:

FULLNAME() = [EmployeeName]

Enables members of the Managers group to see all rows, while users can see only the rows where their username matches the value in the employee_name column:

ISMEMBEROF('Managers') OR USERNAME() = [employee_name]

Supported Tableau functions in policy conditions

Policy conditions support a subset of Tableau functions:

• Logical (except null-related)
• String
• User
• Date
• Number: MIN, MID, MAX

To see which specific functions are supported, in the virtual connection editor, on the Data Policies tab, see the Reference panel on the right.

Note: If the virtual connection has a data policy that contains user functions(Link opens in a new window) (for example, USERNAME()) and you connect to it from a workbook or data source and create an extract there, the extract will contain only the rows that match the virtual connection data policy at the time the extract is created. To take advantage of a virtual connection with user functions in the data policy, use a live connection from the workbook or data source to the virtual connection instead of an extract.

Who can do this

To create a data policy, you must

• have credentials to the database that the virtual connection connects to, and
• be a server or site administrator, or a Creator.

Next steps

After you create a data policy, the next step is to verify that it works as you expect it to. See Test Row-Level Security with Preview as User. Or, if you're ready to share the virtual connection and its data policies with others, see Publish a Virtual Connection and Set Permissions.

Resources

For detailed information about calculations, see Understanding Calculations in Tableau(Link opens in a new window) in the Tableau Desktop and Web Authoring help.

For information about user functions, see User Functions(Link opens in a new window) in the Tableau Desktop and Web Authoring help.

For information about other row-level security options in Tableau, see Overview of Row-Level Security Options in Tableau(Link opens in a new window) in the Tableau Server help.