Template dashboards

A template dashboard is a dashboard that requires some variables to be filled dynamically (i.e. passed to the dashboard when it has to be rendered). These variables are used to filter the content of the dashboard.

For example, you can create a template dashboard for your sales team with a variable that indicates the sales representative who is viewing the dashboard. The dashboard will let him see only its sales.

This is also useful to create a single dashboard and embed it in your application, and display data related only to the user connnected in your application.

In the dashboard editor, such a variable is declared in the 'Global Filter' section, using the {{my_variable}} format. If a global filter is declared, the dashboard is said to be a template dashboard. You have to define the value of this variable to display the dashboard.

Example

As a prerequisite for this example, use the code below in a script to load a data storage with some data.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
import serenytics
client = serenytics.Client()

data = [{'country': 'FR', 'name': 'John', 'quantity': 10},
        {'country': 'US', 'name': 'Mark', 'quantity': 2},
        {'country': 'UK', 'name': 'John', 'quantity': 1},
        {'country': 'US', 'name': 'David', 'quantity': 8}
]

source = client.get_or_create_push_data_source_by_name(name='template dashboard example')
source.reload_data(new_data=data)

Create a simple dashboard using this data storage. You can view this dashboard with the url pattern: https://app.serenytics.com/viewer/webapps/DASHBOARD_UUID.

So far, this is not a template dashboard. To make it template, you need to add a global filter. In the capture below, we created a global filter on the field country, with the operator ==, and the variable name is __countryVar__. The {{ and }} are used to specify to our engine that this is a template variable that must be interpreted, and not a standard string.

Global filter example

When you add this filter, the widgets of the dashboard using this datasource will display an error message:

Missing variable in the payload

To first test your dashboard with variables, instead of dynamically passing these variables, you can start by using a "test" payload defined in the dashboard. Once your dashboard is working with a test payload, you can implement the dynamic payload.

Using a test payload to pass variables

Simulated payload definition

With this test payload defined, our engine knows the value to use for the variable __countryVar__ and the widgets can filter the data accordingly. This test payload is a useful tool to use when designing a template dashboard. But when you load the URL https://app.serenytics.com/viewer/webapps/DASHBOARD_UUID (i.e. when you load the dashboard in the viewer app), the test payload is not integrated. It's only available for test and design purpose within the studio. To have it available in the viewer app, you need to dynamically pass a payload to the dashboard (see section just below).

Section Dashboard variables

There is a section called "Dashboard variables" just below the section to create static filters. This field can be used to hard-code variables values in a dashboard (and use them exactly as described above with the {{myVar}} syntax). This is useful to statically filter several datasources on a single value. This value can be defined once in this field instead of copying it in every static filter.

If you provide a value for a variable here and also provide it dynamically in a payload passed to the dashboard, the dashboard will use the value provided dynamically.

Dynamically passing a payload to a dashboard

In the next two paragraphs, you'll find two ways to create the payload outside of our studio and pass it to the dashboard viewer.

Query-string mode

In this first mode, in order to specify the payload to the viewer, you must pass the payload as a base64 parameter in the URL: https://app.serenytics.com/viewer/webapps/DASHBOARD_UUID?embeddedPayload=BASE64-PAYLOAD

See the example below for a javascript or python code to create the encoded base64 payload:

1
2
3
4
5
6
// Javascript code

var payload={
    __countryVar__: "US"
}
var embeddedPayload = btoa(JSON.stringify(payload))
1
2
3
4
5
6
7
8
9
# python code

import base64
import json

payload = {
  '__countryVar__': 'US'
}
embeddedPayload = base64.b64encode(json.dumps(payload))

This method is very simple but is not safe and thus it can be used only by the owner of the dashboard, unless the dashboard is shared as "public".

Share your dashboard as "embedded" and use the back-end mode for a safe embedding.

Back-end mode

To secure the template dashboard embedding process, you need to safely obtain the URL of the dashboard (configured with the payload) from your back-end.

This URL can be obtained from a POST to the URL: /api/web_app/DASHBOARD_UUID/embed.

Because you need to pass your API key to get authenticated for this URL, you must call this URL from a code not visible by your users (i.e. your back-end).

You must pass the following options to this route:

  • payload: payload to pass to the dashboard
  • expire_in: number of seconds the dashboard URL will be valid

It will return a JSON with a field embeddedUrl. This URL is the URL to use to safely display the dashboard to your user (it already contains a safe token encoding the payload).

See the embed API documentation for more information and code examples.

Example flow of secure embedding

Let say you want your user to access a Serenytics dashboard but you want him to only have access to the data of its business unit.

Here is the flow to achieve that:

Secure embedding flow

  1. In your front-end, when the user loads the page where to embed the dashboard: call an API route on your back-end to get the dashboard URL. This route is a new one you need to create in your back-end (e.g. you can name it get_serenytics_dashboard_url). Of course, your user needs to be authenticated to your system to be allowed to call this API.

  2. In the code of this API (in your back-end), you know which user (from your system) did the call. You can extract its business unit from your database. Then call the /api/web_app/DASHBOARD_UUID/embed API passing it the user's business unit.

  3. You receive (in your back-end) the result from the /api/web_app/DASHBOARD_UUID/embed API. It contains a field embeddedUrl which is a unique URL.

  4. You answer to your front-end (as the answer of step 1) passing it the field embeddedUrl.

  5. You display the embeddedUrl in an iFrame (see iFrame embedding documentation).

This is secure because:

  • the API /api/web_app/DASHBOARD_UUID/embed requires your Serenytics API key, and you call it from your back-end so your user has no access to your Serenytics API key

  • the embeddedUrl returned by the Serenytics API contains only a secure id and not all the payload used to filter the data like in the query string mode. In this mode, the secure id lets us retrieve the corresponding filtering payload inside the Serenytics back-end when a data request is made from the embedded dashboard. The filters are applied directly inside the Serenytics backend and thus cannot be modified by your user.

With this flow, your user can't forge an URL to get data from another business unit.

Note that you must repeat this process each time the user wants to display the dashboard (because the provided URL has an expiration date).

Using the in operator

When using the in operator in the filter:

  • if the type of the filtered column is datetime, the value must be a string (e.g. "month(0)").
  • else, the value can be:
    • a list, for example: ["USA", "France"]
    • the special string "$$all$$" that will not apply any filter (i.e. return all data).

Here is an example to filter with two countries (when using the Serenytics editor to simulate the payload, quotes inside filter value must be escaped):

List filtering with the payload

Here is another example to use the "$$all$$" keyword in our interface:

Using all keyword

Using the payload within a formula

For advanced needs, you can use values passed by the payload inside formulas. In this case, please note that the formula preview is not working and will always display an Incorrect filtering error.

Here is an example:

Using the payload in a formula

In the dashboard, this formula can be tested with the operator is_true.

Filtering dashboard data based on logged in user

It's also possible to use variables based on logged in user inside global dynfilters. For this, you don't need to embed Serenytics inside your page nor develop any code. You only need to have data containing one row by user of your Serenytics organization.

Loading metadata for each user

Create a new data source with your data by user (it can be any kind of source, for instance a CSV or a SQL server). The first column must be named login and its values must correspond to the username of the users of your organization in Serenytics.

Then create a task "Reload user metadata" in the automations section and select the newly created data source. Run the task and you're ready to filter data based on who is viewing your dashboard.

Using user metadata in global filters

Instead of defining a filter such as before country == {{__country_var__}}, you can now use the $$login.variable$$ syntax to filter on user based values. For instance using the same example as previously:

1
country == $$login.country$$

if country was a column of the data source you created previously.