Holistics Docs - End-to-End Business Intelligence Platform

Holistics Documentation

Welcome to the Holistics Documentation page. You'll find comprehensive guides and documentation to help you start working with Holistics as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started

Permission System

Holistics comes with extensive permissions and data access control capability. You can control which groups can access which data, making it easier for users to navigate through reports and improving data security. All users are allocated a role, and can then be added into user groups.


Roles & Groups


There are 3 possible roles on the Holistics platform. Each user will belong to one role.

  • Admin: Admin can manage users, reports, dashboards and billing, etc.
  • Analyst: Can create and edit reports and dashboards whose data source is shared with them. Analyst cannot manage users, or connect new data sources.
  • Business User: Can only view reports and dashboards that are shared with them


Groups can be created by admins, and they are used for organizing users into different categories. Each user can
belong to multiple groups. Examples of user groups:

  • Marketing
  • Engineering
  • Asia
  • Europe
  • Management
  • ...

Report/Dashboard Level Permissions

  • You can share reports, dashboards, or KPI metric sheets to specific users or groups.
  • This works for folders as well. Sharing a folder will automatically share all items inside.


Filter Permissions

Permissions can be included into date and dropdown filters. To do this, expand the "Permissions" field when creating or editing a filter, and then add your permission code into the field.

Syntax References

Filter Permission allows for following input variables:

  • Condition variables
    • if_group: Group name
    • if_user: User email
    • else: No value is needed. This applies to anyone who does not belong to its above condition
  • Outcome variables
    • then_value: Value manually added
    • then_sql [ds_id, query]: Value extracted through a SQL. ds_id is the datasource id
    • then_date_min: Min date value
    • then_date_max: Max date value
  • Optional variables
    • expression: Allows more control over permissions filter. This field defaults to Group1 union Group2 union Group3, where Group1, Group2 and Group3 are added in as in_group. This field could be customized to: Group1 union (Group2 intersect Group3)

Example input code:

- if_group: GroupA
  then_value: valueA
- if_group: GroupB
  then_value: [valueB, valueC]
- if_group: GroupC
      ds_id: 25
      query: select val from tableC
expression: Group1 union (Group2 intersect Group3)

Example code using else:

- if_group: GroupA
  then_value: valueA
- if_group: GroupB
  then_value: [valueB, valueC]
- else:
  then_value: valueD


  • Each permission must contains at least one Condition variable and one Outcome variable
  • expression is usable only in Dropdown Filter
  • then_date_min, then_date_max are usable only in Date Filter
  • else syntax can only be used for filter that returns a single value

Legacy Syntax

The following input variables still work:

  • in_group: The same as if_group
  • value: The same as then_value
  • sql: The same as then_sql[query] but only works in Dropdown Filter
  • date_min/date_max: The same as then_date_min / then_date_max

Example code:

- in_group: GroupA
  value: valueA
- in_group: GroupB
  value: valueB
- in_group: GroupC
  sql: select val from tableC


Restricting Selections for Dropdown Filter

Consider an organization where the employees belong to different country groups: Singapore, Malaysia, Vietnam, etc. For our report, we want users, belonging to country A, to be only able to see data for that country, and users belonging to multiple country groups only to be able to see data from the countries they belong to.

1/ Setup a Country filter with the following permission code:

- if_group: Singapore
  then_value: sg
- if_group: Malaysia
  then_value: [my, vn]
- if_group: Vietnam
      ds_id: 12
      query: select country_code from countryTable

2/ Add the Country filter to your SQL query:

WHERE [[ country IN ({{countries}}) ]]


  • country is the name of the country field
  • countries is the name of the report filter


Add Variable In Filter Permission

This allows admins or analysts to add variable {{ $user.email }} in filter permission.

Consider these tables. By providing a mapping table to match two key tables together (such as employees table with stores table), this means that when employees login to the Holistics platform with their emails, the {{ $user.email }} variable will get passed into the filter query, and pull out the subset of stores that the employee manages.

For an example using our SQL syntax inside the filter permissions, consider these tables; a managers table, a store table and a mapping table that joins these two tables together, a store_user_permissions table.

We have a company where 50 managers manage 100 different stores. Each manager can only see the stores' reports he/she manages. Previously, when managers switch stores, the admins will need to update the changes in their own system and update the permissions in Holistics system. With this feature, they only need to update the tables in their own system, and Holistics will refer to those tables with a query using the {{ $user.email }} variable.

Applying this logic would let us create a filter permission as such:

- if_group: Manager
    ds_id: 25
    query: select store_id from store_user_permissions SUP join managers M ON SUP.user_id = M.id where M.email = {{ $user.email }}


Parent Child Filters

Adding child filters to dropdown filters will impact your permission syntax. Please refer to Setting Up Parent-Child Filters and Dropdown Permissions


Restricting Content for Text Filter

You can make your Text filter read-only and have different values for different groups with filter permission. For example:

- if_group: Singapore
  then_value: sg
- if_group: Malaysia
  then_value: my
- if_group: Vietnam
  then_value: vn

Notes: There is only one value can be applied for one group. If you set multiple values for a group, the first one will be selected.


Restricting Date Selection for Date Filter

Sometimes when working with the Date filter, you want to restrict date range access to specific user groups. For example:
since Singapore site only launches in May, business users from Singapore shouldn't be able to select dates earlier than that.

To do this, apply the following permission syntax to the date filter:

- if_group: Singapore
  then_date_min: '2016-05-01'

This will restrict the user's date selection options:



  • You can also use then_date_max to restrict the maximum date selectable.
  • Right now, only exact date values are supported (i.e. no text values such as 3 months ago).
  • If the user belongs to multiple groups that are defined in the permissions section, the first matching group will be selected.


Sharing Data Sources to Analysts

In order for analysts to create reports or run queries on a data source, that data source must be shared to them.

Admin can share the data source to specific analysts by going to Manage Data Sources page and click on the Share With column.

Note that even if a data source is shared to an analyst, s/he cannot view or modify database credentials information of that data source.

There are several ways of limiting analyst access to data sources. You can connect to the same data source with different database username and password credentials, and add these as separate data sources to be shared with specific analysts.

In this example here, DW-PostgreSQL-Demo-Private and PostgresDemo are actually both data sources using the same database, but with different database username and password credentials saved for each.

DW-PostgreSQL-Demo-Private can only be accessed by "Demo Analyst", so other analysts will not be able to see or select DW-PostgreSQL-Demo-Private as a data source. They can only build queries from the schemas and tables they can access, such as those associated with the database user for the PostgresDemo data source.


Locking Objects

This feature allows admins or analysts to place a lock on a lockable object. Once locked, only admins or the object owner can modify/delete it.

Analysts can only lock their own objects, while admins can lock every lockable objects.

Current lockable objects are:

  • Dashboards
  • Query reports
  • Query templates
  • Shared filters