This guide outlines the complete release flow for Luzmo dashboards — from initial development to production — using groups, collections, and environment-specific API tokens to manage access to dashboards and datasets. It also makes use of the dashboard versioning mechanism to allow validating changes to existing dashboards in your application's different development environments before publishing it to production.

Table of contents

• Related features
  • Dashboard versioning mechanism
    • Publishing a dashboard version to an environment via API
  • Connection overrides to an environment-specific data source
• Setup guide
  1. Creating User Groups
  2. Adding Data to Luzmo
  3. Designing Dashboards in Luzmo
  4. Embedding Dashboards per Environment
     • Embedding in your Development Environment
  5. Deploying Dashboards to Next Environments
     • From Development to Staging
     • From Staging to Production
• Summary

Related features

To achieve a robust setup for your application's different development environments (i.e. where your development, testing, and releasing process occurs), the following Luzmo features can be used:

Dashboard versioning mechanism

By using a dashboard's version history functionality (see here), you can "publish" a certain dashboard version to a specific environment (e.g. production) and keep editing the dashboard in Luzmo's dashboard editor, without changes being immediately reflected in your production environment. When embedding a dashboard using an Authorization token, the production dashboard version would by default be shown if no environment property is specified (by specifying this property, you can control which dashboard version is shown in which development environment of your application). For example, if you want to embed the latest version of a dashboard in your testing environment, you can do so by specifying environment: null when requesting the token:

client.create('authorization', {
  type: 'embed',
  access: { ... },
  ...,
  environment: null
});

Within the dashboard editor's dashboard version history, you can "publish" a dashboard version to one of the environment tags (i.e. production, acceptance, or development); each environment tag can only be associated to a single dashboard version per dashboard. If a certain environment specified in the Authorization token does not exist for an embedded dashboard, it will show the latest dashboard version. There are five acceptable states for the 'environment' property:

• null - load latest version of dashboard
• 'production' (Default value if not specified)
• 'acceptance'
• 'qa' (currently only available via API)
• 'development'

Publishing a dashboard version to an environment via API

By using our API, you can also set the different environment property values mentioned above on a specific dashboard version (i.e. securableVersion) using the following steps:

1. Get the dashboard versions of a specific dashboard

client.get('securableversion', {
  where: {
    securable_id: "<id of dashboard I want to update the version of>"
  },
  attributes: [ "created_at", "name", "updated_at", "environment" ],
  order: [
    [ "created_at", "desc" ]
  ]
});

Note: when you change the dashboard name, it changes the securableVersion name as well. If you hide the name in your dashboard's settings, that is a potential easy reference point. Otherwise, you might just want to look at the created_at property.

2. Update the securableVersion by setting the new environment

Note that a specific environment should only be associated to one dashboard version per dashboard: make sure to remove the environment from a previous dashboard version if it had the same environment associated with it (see step 3 below).

client.update('securableversion', "<id of a securable version>", {
  "environment": "<production | acceptance | development | qa>"
});

3. Remove an existing environment from a dashboard version

client.update('securableversion', "<id of a securable version>", {
  "environment": null
});

Connection overrides to an environment-specific data source

The process from a data source to Embedded Luzmo dashboards generally follows typically looks as follows from a high-level point of view (also see the "Setup" section below):

1. Connect your data source to Luzmo, which will create a "Connection" in Luzmo.
2. Add datasets from this connection
3. Create dashboards which reference columns from those datasets
4. (Optional but recommended) Create a Collection and add the appropriate dashboards and datasets to it
5. Request an Embed Authorization token server-side, which can be used client-side to authenticate your user with Luzmo
6. Embed the Luzmo dashboard in your frontend using the Embed token

If you have environment-specific data sources for each development environment of your application (e.g. both a "staging" and a "production" database), it may seem at first glance that you will need to repeat the first 4 steps for each environment you'd like to support. However, in Luzmo it's possible to create what we call "Templated" dashboards based on datasets from one Connection in Luzmo (e.g. the production or demo database), and then dynamically override the authentication properties of that Connection (host URL, username, password, schema, ...) when requesting an Embed token for your application's (development) users.

In this way, each environment will use the same template dashboard, but the data will be populated from the environment-specific data source. Be aware that (at least) the same table schema (e.g column names and types) must be present in the overridden data source, otherwise you might experience query failures when embedding a dashboard (e.g. due to trying to query a column that doesn't exist in the overridden data source)!

Refer to the "Making a XXX Connection article of your specific data source for more info on how to do account_overrides.

Setup guide

1. Creating User Groups for your internal Luzmo users

The Luzmo application (https://app.luzmo.com, https://app.us.luzmo.com, or your VPC-specific Luzmo app URL) can be considered as your internal dashboard development environment. Access management is organized via user groups, which you can create and manage in your Profile settings:

• Data Group: Responsible for adding data sources and managing datasets.
• Designers Group: Designs and maintains dashboards.
• Embed Group: Handles embedding for each environment.

Embed Group with "Owner" Users

Each environment (Dev, Staging, Production) has a dedicated Luzmo user in the Embed Group, which can be considered "Service accounts". These users:

• Must have the "owner" role in your Luzmo organization (required to be able to request Embed authorization tokens)
• Are members/owners of the Embed Group, who receive owner access to relevant dashboards and datasets
• Have their own "environment-specific" Collection and API key-token pair, which is used to generate Embed Tokens in your application's different development environments:
  • Dev user → grants access to Dev Collection
  • Staging user → grants access to Staging Collection
  • Prod user → grants access to Production Collection

2. Adding Data to Luzmo

Typically handled by the Data Group:

1. Create a connection to your Production database (*) - make sure to share the connection with owner access to the Data Group to allow your "data" colleagues to use and maintain the connection
2. Import and enhance datasets - e.g. rename columns, add descriptions, set up default formats, add derived columns or formulas, etc.
3. Add datasets to the Development Collection
4. Share datasets with:

• Data Group (owner access) -- allows other internal "data" users to maintain this dataset
• Designers Group (use access) -- allows your internal "designer" users to use the dataset in their dashboards, but not modify/share/delete the dataset itself
• Embed Group (owner access) -- allows the "developer" users (i.e. service accounts) to provide access to this dataset in the Embed Authorization request

3. Creating Dashboards in Luzmo

Handled by the Designers Group:

• Use shared datasets to create dashboards
  • If a dashboard is ready to be tested in e.g. your development environment, your designer should publish the latest dashboard version to development
• Add dashboards to the Development Collection
• Share dashboards with owner access to:
  • Designers Group -- allows your internal "designer" users to maintain this dashboard
  • Embed Group -- allows the "developer" users (i.e. service accounts) to provide access to this dashboard in the Embed Authorization request

4. Embedding Dashboards per Environment

Each "Environment-specific" Luzmo user uses its API token to manage any datasets and datasets that should be accessible in that environment, as well as to generate Embed tokens where you can:

• Provide access to resources in their environment-specific Collection, allowing you to separate dashboards between environments
• Use Connection overrides to dynamically point to your environment-specific data source (must be reachable by the Luzmo environment!), allowing you to validate the visualized insights on data in different environments.

Embedding in your Development environment

You can use the Dev Embed User’s API token to generate Embed Authorization tokens that receive access to the Development collection. To point towards the development database, you can use the account_overrides property in the Authorization request; to point towards the development version of your dashboard, you can set the environment Authorization property to development if you published a dashboard version to development, or null to point towards the latest dashboard version.

After setting up the embedded dashboard in your local frontend environment, you should be able to see the development version at e.g. http://localhost:8080/analytics.

5. Deploying Dashboards to Next Environments

From Development to Staging

Once your dashboard has been successfully tested in your Develeopment environment:

1. The Staging Embed User adds the new dashboard (and underlying datasets) to the Staging Collection (via our UI / via API)
2. Publish the dashboard version to acceptance (via our UI / via API)

3. Use the Staging Embed User’s API token to generate Embed Authorization tokens with:

• environment set to acceptance
• account_overrides to redirect Luzmo queries dynamically to your Staging data source

From Staging to Production

• After successful validating your embedded dashboards in staging:

  1. The Production Embed User adds the new dashboard (and underlying datasets) to the Production Collection (via our UI / via API)
  2. Publish the dashboard version to production (via our UI / via API)
  3. Use the Production Embed User’s API token to generate Embed Authorization tokens with:
  • environment set to production (or not specified - the default value is production)
  • No connection overrides needed if you connected your production data source to Luzmo
    • For non-production data sources configured in Luzmo, you can use account_overrides to redirect Luzmo queries dynamically to your Production data source

Your embedded dashboards are now available in your Production environment at e.g. https://yourapp.com/analytics 🎉

Summary

1. In the Luzmo app, you'd have a set of dedicated users and groups that are responsible to connect your data, create dashboards, and embed them in your application's different environments.
2. You can use one (or multiple) Collection(s) per environment to manage environment-specific access to a set of datasets and dashboards (owned by separate Luzmo users to avoid accidental cross-environment access).
3. You can programmatically or manually "roll out" dashboards (and dashboard versions) from one environment to the next, allowing for easy validation in your application's different development environments before releasing the changes to production.