Embedded Dashboard Editor - a summary of the prerequisites

2:30 min

Medium

You're in luck: we created a TL;DR summary to embed the dashboard editor 🎉 The items listed below are the absolute basics: ensuring you got these covered will give you an initial implementation upon which to further extend!

Rights on the dashboards and datasets

First and foremost, it's important that every dashboard and dataset you make accessible for an end-user has the appropriate access rights.

Dashboards

When sharing a dashboard, you choose one of the following rights to specify what an embed user can do with the dashboard:

'read' - gives the embed user the right to only view the dashboard.
use' - next to viewing a dashboard, the embed user is able to create a variant of the dashboard, or duplicate it (dashboard duplication is only supported in editMode “editFull”).
'modify' - besides viewing, duplicating and creating a variant of the dashboard, the embed user can edit the dashboard itself.
'own' besides viewing, duplicating, creating variants and editing the dashboard itself the user may favorite variants for other users and share and delete the dashboard.

This Academy article goes more into detail on associating dashboards for embedded dashboard editor purposes.

Datasets

When sharing a dataset you choose one of the following rights to specify what an embed user can do with the dataset:

'read' - users are only allowed to query the dataset in existing chart(s) that are accessible to them (i.e. the user is not able to use this dataset when creating/editing a dashboard).
'use' - the user is also able to use this dataset when creating or editing a dashboard.
'modify' - the user is able to use this dataset when creating or editing a dashboard, and is able to edit the dataset itself (e.g. change column names, create or alter hierarchies, create or alter derived columns, etc.).
'own' besides being able to use and edit this dataset the user may share or delete the dataset.

Important! For security reasons, it is of utmost importance that multi-tenant (parameter) filters are specified on the dataset level: this ensures that they are always applied when the user queries the dataset directly or via a (new) dashboard. Parameterizable filters can be used to dynamically apply these filters, by overriding the parameter value(s) when requesting an embed token for your user. Instead of using parameterizable filters, you could also specify static filters when configuring a dataset’s embed filters or when requesting embed authorization tokens.

This Academy article goes more into detail on associating datasets for embedded dashboard editor purposes.

Role in the authorization request

Now that you've indicated which dashboards and datasets should be accessible in which way, it's time to indicate for each embed user which role it should have. This is done in the authorization request in your backend, a short description of each role can be found below!

'viewer' - embed users that should only be able to view and interact with one or more dashboards/variants/duplicates.
designer' - embed users that should be able to create, edit, view and interact with one or more dashboards/variants/duplicates.
'owner' - embed users that should be able to create, edit, view and interact with one or more dashboards/variants/duplicates, and next to that they should be able to favorite dashboard variants for other embed users within their suborganization.

This Academy article goes more into detail on the different properties of the authorization request.

editMode in the frontend embedding library

Last but not least, we should make sure that the dashboard is loading in the editMode that your end-user requires. Below are all different editModes briefly discussed!

'view' - enables your users to view and interact with an embedded dashboard, without having the option to change the dashboard itself!
editLimited' - useful if you have your own dashboard navigation in your application (e.g. a sidebar containing dashboard tabs or a dropdown) and would like the user to edit (some of) the dashboards (e.g. by adding an “Edit” button that toggles the editMode between “view” and “editLimited” mode).
'editFull' - in this mode the editor itself will provide navigation to new or other accessible dashboards! This is useful if you have a dedicated place in your application, where users should be able to create & edit all their accessible dashboard(s) (e.g. in your navigation bar, you have a “Dashboard editor” tab that should show the embedded dashboard editor).

This Academy article goes more into detail on the embedding possibilities in the frontend libraries we provide.

That's it. Properly setting these properties will enable dashboard customization by your users, in your application!