Skip to main content

Embedded: Permission Settings

Definition

Row-level Permission (RLP) is one of the three types of permission control that Holistics supports. RLP allows you to control which record users can retrieve from the database. Our Embedded Analytics support RLP.

Note that when Permission Setting is set, the data restriction rules are also applied to the related filters.

Why do you need RLP?

When your embedded (or application) users visit your embedded dashboard, without RLP or any data restriction, they can see all the data which potentially leads to data leakage.

For example, you're building an embedded dashboard for your multi-national ecommerce company and your Ecommerce sample shows sales for all the stores worldwide. Without RLP, no matter which manager signs in and views the report, they all see the same data. The CEO has determined each country manager should only see the sales for the stores they manage. Thus, RLP allows the CEO to restrict data based on the area they manage.

ERD

By applying the RLP on the country name field of the model country, whenever your country managers login, the condition country.name = 'their_country' is applied so they can only view data from their countries.

How it works

General structure of Embedded Row-level Permission

Permission Settings

permissions = {
"row_based": [
{
"path": {
"dataset": "dataset_name"
"model": "model_name"
"field": "field_name"
},
"operator": "expected_operator",
"modifier": null,
"values": [
"your_expected_value"
]
}
]
}

row_based property is an array with multiple permission rules, each Permission Rule is the combination of Operator, Values, and Modifier which construct the condition applied to restrict data of a particular field.

  • The Path will help define the exact field on which the condition will be applied. Since our row-level-permission in applied on dataset level, the path needs include dataset unique name, data model name and field name.

  • After defining the exact field, Operator will specify the comparison type (IS, IS NOT...) for the field.

  • Values are used to restrict the data for that particular field

  • Modifier (optional): only available for some of the operators in Date filter (for example, next, last X days/months/years.

Note

Dataset's unique name at this moment is not presented explicitly but you can still retrieve that information via our Embedded Analytics Sandbox.

We recommend that you should use our Embedded Analytics Sandbox to retrieve the exact path in your RLP settings

Apply Row-level Permission to retrict data based on users

Permission Syntax

Below is a sample code of permission settings to ensure:

  • General Manager can see data from all countries.
  • Vietnam Manager can only see data from Vietnam.
  • Consultant can only see stores in Ha Noi.
country = []
cities = []

if (current_user().email == "[email protected]") {
country = ['Vietnam']
} else if (current_user().email = "[email protected]") {
country = ['Vietnam']
cities = ['Ha Noi']
}

permissions = {
row_based: [
{
path: {
"dataset": "ecommerce"
"model": "ecommerce_countries"
"field": "country_name"
},
operator: 'is',
values: country
},
{
path: {
"dataset": "ecommerce"
"model": "ecommerce_cities"
"field": "city_name"
},
operator: 'is',
values: cities
},
]
}
Note

Do note that the sample code above is only for you to understand the basic concept of our Row-level Permission. You can modify the code as your preference and use cases.

Continue with the rest of your setup

After done setting up Row-level Permission, you can continue with other setups to embed the dashboard into your application. For more information, please refer to this doc

FAQ

Question: Why do permissions have different datasets from what we originally selected?

Embedded Permision Settings

Answer: This happens because the dataset was renamed.

  • The UI on the left displays the title of the dataset that has been renamed. The code on the right uses the Dataset’s unique name.
  • The Dataset’s unique name is auto-generated when the dataset is created. we don't update Dataset’s unique name to avoid breaking existing embed payloads.

Let us know what you think about this document :)