How to Embed your Holistics Dashboard

Embedded Analytics is the integration of analytical capabilities within your business platform to serve multiple purposes: build dashboards for your clients, your investors or your managers without forcing them to create Holistics accounts.

The target audience for this guide is Developers.

How to generate Embed Code

1. Enable Embedded Analytics

Go to Embed Link Manager, click Configure button and enable it.

Embedded Analytics

From your Dashboard, select Settings > Dashboard Preferences > Embedded Analytics.

After generating the unique embed link for the Dashboard, you will see the Embed Code and Secret Key.

  • Embed Code: Unique code of your embed link
  • Secret Key: Unique secret key used to encode/decode data

Then click Preview to go to Embedded Analytics Sandbox.

https://files.readme.io/ee7f087-embed_preview.png

3. Configure Embedded Analytics Sandbox

Please note that the purpose of permission and filter settings in Embedded Analytics Sandbox is only to generate embed code so that you can customize it later when embedding it into your application.

3.1 Permission Settings

Our permission system for embedded link allows Row-based/horizontal data access . This means you can control which records a user can retrieve from your organization’s database.

Embedded Analytics

In order to set Permission, click on + Add Permission and choose the field to which you will apply the permission rule.

For more information about our Permission Settings concept, please refer to our doc here.

3.2 Filters Settings

You can set default value for your Dashboard’s filters or hide them to prevent your Dashboard’s viewers from adjusting the filter’s values.

Embedded Analytics

If you do not use our example code?

For now, we support generating sample code for Ruby, NodeJs, Python, Elixir.

If you do not use any of our example language? No worries, please follow our instructions below.

1. Pick your JSON Web Tokens library

We use JSON Web Tokens (JWT) to create security tokens. You can find a JWT library suitable for your needs here: https://jwt.io/

2. Get encoded token

Get encoded token with these JWT options:

> Hashing algorithm: HS256
  > Build your filter config folow these options:
    const filters = {
      "filter_name": {
        "hidden": boolean,
        "default_condition": {
          "operator": 'YOUR_EXPECTED_OPERATOR',
          "values": [YOUR_EXPECTED_VALUES],
          "modifier": 'YOUR_EXPECTED_MODIFIER'
        }
        ...
      }
    };
    const permissions = {
      "row_based": [
        {
          "path": "`dataset`.`data_model`.`field`",
          "operator": 'YOUR_EXPECTED_OPERATOR',
          "values": [YOUR_EXPECTED_VALUES],
          "modifier": 'YOUR_EXPECTED_MODIFIER'
        }
        ...
      ]
    }
  > Payload: Expire time (`exp` in Unix Timestamp) and identifier variables, example:
    ```
      {
        "exp": 1537867461,
        "filters": filters,
        "permissions": permissions
      }
    ```
  > Sign it with Embed Link's secret key

There are fields you need to fill in to run the application.

Filter

  • Filter name: the name of the filter. This value should be unique, and you can get the filter_name in the embedded analytics preview.
  • Hidden: accepts true or false value. If you want to hide any filter in your embedded dashboard, you have to set hidden to true.
  • Default Condition

    • Operator: Each data type has its own set of operators:
    • Text filter
    • Number Filters
    • Date filter
    • True/False filter
    • Values: your expected value set for the filter
    • Modifier:
    • If your filter is in date format and its operator is last or next, choose one of the modifier (day, week, month, year)
    • If your filter is not in date format or date format but its operator is not last or next, leave this null.

Permission

  • Path: define the exact field on which the condition will be applied. You can get the dataset unique name, model name and field name in the embedded analytics preview.
  • Operator: Similar to filter operators.
  • Value: your expected value set for your row-level permission
  • Modifier: Similar to Filter Modifier.

Payload

The payload should follow this schema

payload = {
    "permissions": permissions,
    "filters": filters,
    "exp": expire time,
}

3. Render iFrame

Use the encoded token above and embed_code render the iframe below in your web app.

<!-- Embedded Ruby(erb) template -->
<iframe src="https://staging.holistics.io/embed/<%= embed_code %>?_token=<%= token %>"
  style="width: 100%; height: 600px;"
  frameborder="0"
  allowfullscreen>
</iframe>

Example

Let’s say you have a master Dashboard illustrating the performance of your Ecommerce business. You are expected to build an embed dashboard for your Managers at different hierarchical levels.

Also, each store has a dissimilar dataset to manage and explore: Dataset Store 1, Dataset Store 2 and Dataset Store 3 and all of them are being used in the Dashboard.

  • Dataset Store 1: Countries model, Cities model, Stores model, Performance, Employees, etc.
  • Dataset Store 2: Countries model, Cities model, Stores model, Performance, Employees, etc.
  • Dataset Store 3: Countries model, Cities model, Stores model, Performance, Employees, etc.

Expected result

When users log in your admin page:

  • User A - CEO: can see revenue of all stores
  • User B - Vietnam Manager: can see revenue of all stores in Vietnam - she can select store 1, 2, 3
  • User C - HCMC Manager: can see revenue of all stores in HCMC - she can select store 1, 2
  • User D - Store 1 Manager: can see revenue of store 1 only

Set Permission Settings

In order for the permission to be applied to all widgets/reports in the Dashboard, you need to set permission for Countries, Cities and Stores on all 3 datasets.

The code should be like this:

// If user_a (general manager) then country = 'all', city = 'all', store = 'all'
// If user_b (from store US) then country = 'Vietnam', city = ['Hanoi', 'HCMC'], store = ['1', '2', '3']
// If user_c (from store US) then country = 'Vietnam', city = 'HCMC', store = ['1', '2']
// If user_d (from store US) then country = 'Vietnam', city = 'HCMC', store = '1'

if ($user_a) $country = ['Vietnam', 'US']; $city = ['Hanoi', 'HCMC', 'LA'];  $store = ['1', '2', '3', '4', '5']
if ($user_b) $country = 'Vietnam'; $city = ['Hanoi', 'HCMC']; $store = ['1', '2', '3']
if ($user_c) $country = 'Vietnam'; $city = 'HCMC' ; $store = ['1', '2']
if ($user_b) $country = 'Vietnam'; $city = 'HCMC' ; $store = '1'

permissions = {
  "row_based": [
    {
      "path": "store1.countries.name",
      "operator": "is",
      "values": $country,
      "modifier": null
    },
    {
      "path": "store1.cities.name",
      "operator": "is",
      "values": $country,
      "modifier": null
    },
        {
      "path": "store1.stores.name",
      "operator": "is",
      "values": $store,
      "modifier": null
    }
        {
      "path": "store2.countries.name",
      "operator": "is",
      "values": $country,
      "modifier": null
    },
    {
      "path": "store2.cities.name",
      "operator": "is",
      "values": $country,
      "modifier": null
    },
        {
      "path": "store2.stores.name",
      "operator": "is",
      "values": $store,
      "modifier": null
    }
        {
      "path": "store3.countries.name",
      "operator": "is",
      "values": $country,
      "modifier": null
    },
    {
      "path": "store3.cities.name",
      "operator": "is",
      "values": $country,
      "modifier": null
    },
        {
      "path": "store3.stores.name",
      "operator": "is",
      "values": $store,
      "modifier": null
    }
  ]
}