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

Embedded Analytics

Help you embed a Holistics dashboard inside your own web application so that your customers/users can view the data.

What is Embedded Analytics

Holistics Embedded Analytics helps you embed a Holistics dashboard inside your own web application so that your customers/users can view the data.

Sample Use-cases

  • Embed inside your CRM Application, set up the right dashboards for the right customers
  • E-commerce/Retails: Embed dashboards into Web/Mobile App to deliver insights to each merchant
  • Include your Dashboard or Report publicly on your website

How To Use

1. Enable Embedded Analytics

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

2. Create Embed Link for Dashboards

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

After generating the unique embed link for the Dashboard, you will see 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 Embed Analytics Sandbox.

3. Configure Embedded Analytics Sandbox

Please note that the purpose of all the 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. Enable Export Data

By default, your viewers cannot export the data. When checking this, the dashboard’s viewers can download your data as CSV or Excel.
The embed code generated from this setting

settings = {
  "enable_download_data": true
}

Please note that if you don't include the lines above, your users cannot export data (which is the same as "enable_download_data": false)

3.2. Permission Settings

Permission Settings can be used as access restrictions for some particular user groups when viewing your Embedded Dashboard. For example, you don't want your dashboard viewers from Vietnam to see data from Singapore, that's when Permission Settings jump in and help control it.

Our permission is currently Row-based/horizontal data access meaning that you can control which records a user can retrieve from your organization's database.

Each permission setting comprises of path, operator, values and modifier

The combination of Operator, Values, and Modifier constructs the condition that will be applied to restrict data of a particular field.

The Path will help define the exact field on which the condition will be applied. Since the field name could be identical in 2 different models so the path will include dataset uname, model name, and field name.

permissions = {
  "row_based": [
    {
      "path": "ecommerce.ecommerce_cities.name",
      "operator": "is",
      "values": [
        "Ho Chi Minh",
        "Ha Noi"
      ],
      "modifier": null
    },
    {
      "path": "ecommerce.ecommerce_orders.status",
      "operator": "is",
      "values": [
        "delivered"
      ],
      "modifier": null
    },
    {
      "path": "orders_master.orders_master.status",
      "operator": "is",
      "values": [
        "cancelled",
        "refunded"
      ],
      "modifier": null
    }
  ]
}

Some notes:

  • Row-based data access need to be applied to all the datasets that need restriction
  • If the widget does not reach the field in the path (due to lack of necessary relationship), the condition will not be applied to that widget

Let us take a quick example, your dashboard is using data from 2 different datasets Sales and Product.

  • Sales dataset includes: deals, organizations, and country
  • Product dataset includes: features, users, and country

If you want to apply restriction on country_name field in country model, remember to do that in both Sales and Product datasets.

3.3. Filter Settings

You can pre-define the default filter value that will be automatically applied to the embedded dashboard.

If there are any dashboard filters that you don't want your users to see or change, you could easily hide them using the syntax "hidden": true, .

filters = {
  "gender": {
    "hidden": false,
    "default_value": {
      "operator": "is",
      "values": [
        "f"
      ],
      "modifier": null
    }
  },
  "country": {
    "hidden": true,
    "default_value": {
      "operator": "is",
      "values": [
        "Vietnam"
      ],
      "modifier": null
    }
  }
}

4. Run and Preview your Generated Code

To check out your embed link present, you could click on Run.

5. Integrate Into Your Application

Note that your customers do not have to sign in inside Holistics to see the shared reports. Therefore, you are required to issue an encrypted token for your customer. The token is for us to:

  • Correctly identify which of your customers is viewing the dashboard.
  • Prevent your customers from faking their identity by simply changing the parameters inside the URL.
  • Expire the token after a specified period of time.

We use JWT (JSON Web Token) as a mechanism to authenticate the code. This is how it works:

  • When a customer visits your app that needs embedding Holistics, your backend will take the customer ID and generate a token based on the secret key above.
  • You then render an iframe pointing to the embed link, with the token baked into it.
  • Holistics then use this token to authenticate and figure out which Customer is logging in, and display your dashboard with only that customer's data.

Note: To send multiple values to your multi-select dropdown, just put an array in your payload. Example:

payload = { 
  brands: ['singarore', 'india', 'usa'],
  exp: expired_time
}

Sample Code (In Ruby)

First, install jwt gem. Do this in your Gemfile:

gem 'jwt'

In your controller:

ruby
SECRET_KEY = "YOUR_SECRET_KEY"
EMBED_CODE = 'YOUR_EMBED_CODE'
BASE_URL = 'https://secure.holistics.io' 

# Note that expired_time is of type Unix Time. E.g 1498795702
expired_time = Time.now.to_i + 60 * 60 # expire in 1 hour 

# Permission Rules and Filter Display Settings
permissions = {
    row_based: [
    {
            path: 'revenue.countries.country_name',
      operator: 'is',
            values: country
        },
        {
            path: 'revenue.cities.name',
      operator: 'is',
            values: city
        },
        {
            path: 'revenue.stores.id',
      operator: 'is',
            values: store
        }
  ]
}
filters = {
    country: {
        hidden: false,
        default_condition: {
      operator: "is",
      values: filters_country
      modifier: null
    }
    }
}

# Symbol customer_id and exp must not be modified.
payload = {
  permissions: permissions,
  filters: filters,
  exp: expired_time
} 

# Encode data, generate token
token = JWT.encode(payload, SECRET_KEY, 'HS256') 

# The iframe URL:
iframe_url = BASE_URL + '/embed/' + EMBED_CODE + '?_token=' + token

Then in your view, simply include an iframe with that URL:

erbruby
<iframe src="<%= iframe_embed %>" 
  frameborder="0" 
  style="width: 100%;height: 600px" 
  allowfullscreen>
</iframe>

The final iframe code would look like:

<iframe src="https://secure.holistics.io/embed/73hfu41h8ih801mc?_token=8bho21nv7gpuiad78tas9gbanp8hv" 
  frameborder="0" 
  style="width: 100%;height: 600px" 
  allowfullscreen>
</iframe>

Security

For security purpose, it's recommended to use HTTPS when embedding Holistics in your side.

Secret Key

The key we issue you in step 2 is to sign your payload with HMAC 256 signature mechanism. This signature is for us to check the payload's integrity and prevent people from tampering and modifying your payload during the request.

Token Expiration

You must specify a time to expire your issued JWT. The recommended expired time is 24 hours after you issue the token.
The reason behind this is to deal with the situation when someone steals the JWT of your customer (not difficult to do so) and issue it elsewhere.
The stolen token will be expired in a short time so damage is minimized.

Sensitive Data

Note that the JWT only allows us to check the integrity of the received payload. No cryptography is involved in JWT, and your payload's information is not securely concealed from others. Please do not include any sensitive data inside the payload

Reset Secret Key

In case your secret key is leaked, you can go to the embed analytics editing section and click Reset Secret Key.

FAQs

Why so complicated, all this JWT and extra code?

Our Embedded feature is designed for use cases where our clients want to embed a dashboard into their own application, where when each of their customers log in they will see different data, i.e a restaurant ordering SaaS system will use Holistics Embedded to provide analytics to their individual restaurant customers, where each restaurant only sees data related to their own restaurant.

Since the cross-customer data security is important, there is the need for the extra work required to ensure encryption is properly set up.

In short, the additional coding effort is there to ensure:

  • Multi-tenancy data permission: Making sure each of your customers will see data related to themselves only.
  • The URL will expire at some point in the future, preventing anyone having access to the URL to pull the data.

InvalidAuthenticityToken error

Sometimes you'll receive this error:
ActionController::InvalidAuthenticityToken

There are 2 reasons

  • Make sure your site has https
  • Enable 3rd-party cookies in your browsers

Access defined for localStorage

Uncaught SecurityError: Failed to read the 'localStorage' property from 'Window': Access is denied for this document

If you have an issue showing the embed, please check browser's console log for the error:

  1. Please open Chrome settings, type "third" in the search box, click the Content Settings button and view the fourth item under Cookies.
  2. Make sure that the option Block third-party cookies and site data is unchecked.

If this setting is checked, third-party scripts cookies are disallowed and access to localStorage may result in thrown SecurityError exceptions.

Updated about a month ago


Embedded Analytics


Help you embed a Holistics dashboard inside your own web application so that your customers/users can view the data.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.