How to Use Luzmo's Embedded Dashboard Editor in Your SaaS Application

February 10, 2022

Tuana Çelik

Let your customers explore their own data inside your SaaS product. This demo will walk you through how to set up Luzmo's embedded dashboard editor.

Luzmo released the Embedded Dashboard Editor. It is a sandbox branded analytics environment in your core application. Here, your product users can create, design, and edit their own dashboards. It exposes capabilities to your end users within the scope of control you decide to grant them. The rights access range from view only to cloning and editing existing dashboards or creating new ones.

The Embedded Dashboard Editor empowers your users with their own data analytics playground. In other words, citizen developers can now take charge of their own data! As a developer or data scientist, you can now focus on the most complex and urgent tasks.

Follow the steps in this article to integrate the Embedded Dashboard Editor into your application. We’ve also provided sample code for you on GitHub.

For detailed instructions on configuration and user management, check out the Academy Course.

Let’s dive in!

A Sneak Peek At The End Result

For use with this tutorial, we’ve published an open repo. This repo allows you to locally run an application that includes the Embedded Dashboard Editor. Let’s see what it looks like.

Example Application

For this demo, we’ve used dashboards about beer 🍻 – because who doesn’t like beer! The demo application embeds Luzmo dashboards the same way you normally would. Users would see and interact with a dashboard when they log in and that’s it. Users can switch to Edit Mode by clicking a button on the bottom left corner of the application. This turns the application into a sandboxed Luzmo dashboard editor.

Let’s look at what happens when someone who has the role designer logs into the application. We will look deeper into roles later!

How to switch to edit mode in Luzmo's embedded dashboard editor

The user can switch to ‘Editor Mode’. In this example, we provide the user the freedom to switch between two edit modes: editFull and editLimited. More on edit modes coming in the next section.

In edit mode, the user has access to either all or some of the following, depending on the edit mode and the rights the user has for a specific dashboard:

  • Create and/or edit a dashboard
  • Create and/or edit a variant of an existing dashboard
  • Set a variant of a dashboard as their favorite
  • Share dashboards and variants with others in their organization

However, if a user with role viewer were to log in, they won’t be able to switch to any of the edit modes.

"Mode change unauthorized" message when someone tries to edit dashboards who does not have the rights to do so

The owner role is similar to a designer. Except the owner can also set a variant as the default for others in their organization (favoriting).

We provide a lot more detail on the different roles and what they mean in our Academy Article.

Enable Embedded Dashboard Editor in Your Application

Let’s have a look at how we get this set up. To follow along, you can clone the example repo on which this tutorial is based. The has explanations on how to locally run the project as well.  

We will also have a brief overview of what the different rights and roles mean in practice. For a detailed description of how to manage different roles and access rights, please visit our in-depth Academy Course.

Integration Rights

First, we have to set up the backbone of any embedding that takes place with Luzmo; the Integration. For the Embedded Dashboard Editor to work, we first need to set the permissions on the Integration we wish to use.

An Integration has two main components: dashboards and datasets. Users will have access to all dashboards and datasets associated with the Integrations they have access to via SSO tokens. When associating a dashboard or dataset to the Integration, specify the rights the user will get to that dashboard or dataset. The user will be bound to these access rights, even if they are using the resource in the Embedded Dashboard Editor.

For example, a dashboard set to ‘Can view’ can’t be edited, even if it’s in an integration you use for the Embedded Dashboard Editor. You can set the following dashboard rights in your Integration.

User rights in a Luzmo integration

Can view: The user can view and interact with the dashboard, but can not edit or create dashboard variants.

Can use: Next to being able to view and interact with the dashboard, the user can duplicate and create a variant of this dashboard.

Can edit: Besides viewing, interacting, duplicating, and creating a variant of the dashboard, the user can directly modify the original dashboard.

In most cases, ‘Can use’ will probably be the most appropriate permission for dashboards that you want to use in the Embedded Dashboard Editor. This will allow the user to use the original dashboard as a starting point of which they can create variants and edit themselves. They will, however, not have access to edit the original one. Only a designer or owner with ‘Can edit’ permissions will be able to edit the original dashboard.

The rights for datasets follow the same principle. You can read all about it in more detail in our Academy Course.

So first, we set the dashboards and datasets to ‘Can use’.

User Roles

There are 3 user roles:

  • Viewer: This user will never be able to switch to edit mode. Not even within an application which enables the Embedded Dashboard Editor. They can, however, view dashboards shared with them.
  • Designer: This user can view, edit and create dashboards. They can create variants of dashboards and set them as their favorite. They will see the favorited variant by default, instead of the original dashboard. They can share dashboards or variants with others in their organization too.
  • Owner: This user is much like a designer, but with a crucial difference. An owner can also set dashboards or variants of dashboards as ‘favorites’ for others in their organization.

Again, all of these capabilities are bound to the rights you defined in the Integration. The set of capabilities a user will get also depends on the edit mode, selected either by the user or pre-defined by you. We discuss this below.

For more detail on user roles, please visit the Academy Article about creating the correct SSO tokens for different roles.

Edit Modes

There are 2 edit modes available: editFull and editLimited.

Only designers or owners can switch between edit modes. In this demo application, designers and owners can pick which edit mode they want to be in. However, in reality, you may want to define this in your application yourself based on your use case.

  • editFull: The user can access all dashboards in the Integration, all other dashboards they’ve created or that were shared with them. They can also create new ones, duplicates, or variants of existing dashboards (depending on their role). If you use this mode, you don’t need to use getAccessibleDashboards to provide navigation to your user. The Embedded Dashboard Editor will already provide this functionality. Use this mode to have one sandbox location in your app where users can freely create, edit, and navigate between dashboards.
  • editLimited: Users can create variants and edit the dashboard(s) you’ve provided them. They can also see and edit other variants they’ve created or that have been shared with them. That is if the person who shared it gave the proper rights. The users can’t create new dashboards. They can only access the dashboards in the Integration that the application provides. This is because there is no navigation within the Embedded Dashboard Editor. Use this mode if you have your own dashboard navigation in your application. This could be a sidebar containing dashboard tabs or a dropdown.

Creating the Luzmo Client and  SSO token

First, you need to create an SSO token for the user. This is where we will tell Luzmo what role the user has. To do so, we need to create a Luzmo client in server.js. This is done the usual way we know and love.

Don’t forget to create an API key and token in your Luzmo account for this step.

The next step of creating an SSO token is much the same as before the Embedded Dashboard Editor was introduced. The only difference here is that you have to provide the role of the user. So, we create an /authorization endpoint in server.js:

You can provide a few flags to enable feature_overrides. For example, to allow users to create alerts or exports. You can use feature flags to modularly control which elements of the editor are visible to the user. For a detailed run-through of these options, check out this Academy Article.

💡Note that if you have cloned the example repo and are running this locally, you can provide the Integration ID in the .env variables.

This creates an authorization token for the user ‘John Doe’ with the role designer. If you run the application at this point, you will see that John Doe can switch to Edit Mode freely.

Try changing the role to viewer and rerun the application. You will notice that John Doe can no longer switch to Edit Mode.

Enabling Edit Mode

Great, so we created a user with a certain role. But how does the switching of modes actually work in the UI?

The Embedded Dashboard Editor is an additional capability of the existing Luzmo Embed Library. We have introduced a new property and corresponding function to our Embed API: editMode and setEditMode.

Embedding the Dashboard(s)


To embed the dashboards, we have to set the authKey, authToken, and dashboardId (or dashboardSlug) of the Luzmo-dashboard component.

Now let's walk through these steps in detail.

In the example repo, we use the Luzmo Web Component. So first, we add the Luzmo-dashboard element to index.html in the frontend.

The options we’ve filled in here are largely cosmetic and aren’t necessary. What’s new is the editMode option that has been set to view here. If you don’t provide a value for the editMode, it will be set to view by default.

The dashboard element is now set to view mode, but the element hasn’t been filled yet with a dashboard. To do so, we use the usual embedding steps of setting the authKey, authToken, and dashboardId of the Luzmo-dashboard component. In main.mjs, we retrieve the authorization key and token from the /authorization endpoint we created in the previous step.

In this example, we provide a sidebar with all available dashboards in the Integration. However, this is not necessary. If you expose the Embedded Dashboard Editor in editFull mode, designers and owners can navigate between the available dashboards in the UI anyway. This step depends entirely on your use case and UI preferences. In our demo, we set the dashboardElement.dashboardId via a populateMenu function in ui.mjs, where we set the id of the dashboard as follows.

Setting the Edit Mode


We retrieve the requested mode from the frontend (or you predefine it in your application) and call the setEditMode() function on the dashboard element.

Now let's walk through the steps in detail.

We set up the ‘To Edit Mode’ button to call a function that will change the editMode of the dashboard element. This function uses the new setEditMode function in ui.mjs:

And in main.mjs:

Note: You can also change the editMode property directly in the dashboard component (dashboardElement) while providing a dashboardId/dashboardSlug. This will automatically load the new dashboard in the specified editMode.

Advanced – Retrieving User Roles from Auth0

That’s all you need to set up the Embedded Dashboard Editor in your application. However, the above scenario won’t necessarily (and probably shouldn’t) translate to what your real-world setup would be.

For starters, you probably don’t want everyone to have a designer role. Or allow everyone to switch between all the different edit modes to their will. You will most likely want to manage this via an authentication layer. So in this section, I will show you how to achieve this with Auth0.

To set up your application with authentication enabled, we’ve provided some example code in the repository. You will find this in the same repo as the above section, but on the authentication branch. The has instructions on how to install and run this version of the application.

Note: Everything in this step is much the same as the Multi-Tenancy on Luzmo Dashboard with Auth0 Tutorial. If you are completely new to Auth0, we suggest you do step 2, Create an Application and Users with Auth0, in the above tutorial first.

Define User Role in app_metadata

In Auth0 User Management, we first need to set the users’ roles in their app_metadata. In this version of the demo app, we stick to our usual mascots Brad Pots and Angelina Julie. Here is what their app_metadata looks like.

Note: If you already have a Login Rule set up in the Auth Pipeline, you can ignore the next step. You can also remove everything above outside of the Luzmo property.

Create a Login Flow

Auth0 moved from using Rule- to Action-based flow. Luzmo (formerly also has an Auth0 Integration which you can install to avoid writing an Action yourself. We will go through the two options of either installing the integration or creating your own action.

In Auth0 Actions, select the Login Flow as seen below.

Configuring a login flow in Auth0 for your Luzmo embedded dashboard editor

Here, you can drag and drop your pre-installed Luzmo Integration as shown below.

Creating your pre-installed Luzmo integration in Auth0

Or, you can create your custom Action which could look like the following.

Finally, don’t forget to hit Apply!

Notice how we include everything in user.app_metadata.Luzmo. This is why we put everything we need in a Luzmo object in app_metadata. This Action might have to look different for you if you want to have a custom structure for your users’ app_metadata.

Retrieve User Information from Auth0

Finally, we need to retrieve user information from Auth0. The authentication branch of the example repo gives instructions on how to set up auth_config.json. Once done, you can change your /authorization endpoint to the following.

Notice how you could also provide integration_id through app_metadata instead.

And that’s all! You’ve successfully added the Embedded Dashboard Editor to your application, with a multi-tenant setup.


Build your first embedded dashboard in less than 15 min

Experience the power of Luzmo. Talk to our product experts for a guided demo  or get your hands dirty with a free 10-day trial.