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](/article/m8p1kx5f#related-features) - [Dashboard versioning mechanism](/article/m8p1kx5f#publish) - [Publishing a dashboard version to an environment via API](/article/m8p1kx5f#api-publish) - [Connection overrides to an environment-specific data source](/article/m8p1kx5f#connection-overrides) - [Setup guide](/article/m8p1kx5f#setup) 1. [Creating User Groups](/article/m8p1kx5f#luzmo-development-users) 2. [Adding Data to Luzmo](/article/m8p1kx5f#adding-data) 3. [Designing Dashboards in Luzmo](/article/m8p1kx5f#creating-dashboards) 4. [Embedding Dashboards per Environment](/article/m8p1kx5f#embedding-dashboards) - [Embedding in your Development Environment](/article/m8p1kx5f#dev-embedding) 5. [Deploying Dashboards to Next Environments](/article/m8p1kx5f#deploying-dashboards) - [From Development to Staging](/article/m8p1kx5f#dev-to-staging) - [From Staging to Production](/article/m8p1kx5f#staging-to-prod) - [Summary](/article/m8p1kx5f#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](https://academy.luzmo.com/article/nnqsrikn)), 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**: ```javascript 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](https://developer.luzmo.com/api/updateDashboard%20Version), 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 ```javascript client.get('securableversion', { where: { securable_id: "" }, 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). ```javascript client.update('securableversion', "", { "environment": "" }); ``` #### 3. Remove an existing environment from a dashboard version ```javascript client.update('securableversion', "", { "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](/article/m8p1kx5f#setup) below): 1. [Connect your data source](https://academy.luzmo.com/article/kl6fy1uz) to Luzmo, which will create a "**Connection**" in Luzmo. 2. [Add datasets](https://academy.luzmo.com/article/kl6fy1uz) from this connection 3. [Create dashboards](https://academy.luzmo.com/article/j53aq50h) which reference columns from those datasets 4. (Optional but recommended) [Create a Collection](https://academy.luzmo.com/article/mn5a4knx) and add the appropriate dashboards and datasets to it 5. [Request an Embed Authorization token](https://academy.luzmo.com/article/a4coimuo) server-side, which can be used client-side to authenticate your user with Luzmo 6. [Embed the Luzmo dashboard](https://academy.luzmo.com/article/06trr3t5) 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](https://academy.luzmo.com/category/b3639a29-2124-4374-9a51-ec5c5522c55a) 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](https://academy.luzmo.com/article/h1lph2xo), add [derived columns](https://academy.luzmo.com/article/bly4il0e) or [formulas](https://academy.luzmo.com/article/52tm82oo), 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](https://academy.luzmo.com/article/8fy44xn4) 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](https://developer.luzmo.com/api/createAuthorization) 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](https://academy.luzmo.com/article/06trr3t5), 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](https://academy.luzmo.com/article/mn5a4knx) / [via API](https://developer.luzmo.com/api/associateCollection)) 2. Publish the dashboard version to `acceptance` (via [our UI](https://academy.luzmo.com/article/nnqsrikn) / [via API](https://developer.luzmo.com/api/updateDashboard%20Version?exampleSection=Dashboard%20VersionUpdateDefaultRequestBody)) 3. Use the **Staging Embed User’s API token** to [generate Embed Authorization tokens](https://developer.luzmo.com/api/createAuthorization) 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](https://academy.luzmo.com/article/mn5a4knx) / [via API](https://developer.luzmo.com/api/associateCollection)) 2. Publish the dashboard version to `production` (via [our UI](https://academy.luzmo.com/article/nnqsrikn) / [via API](https://developer.luzmo.com/api/updateDashboard%20Version?exampleSection=Dashboard%20VersionUpdateDefaultRequestBody)) 3. Use the **Production Embed User’s API token** to [generate Embed Authorization tokens](https://developer.luzmo.com/api/createAuthorization) 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](/article/m8p1kx5f#luzmo-development-users) that are responsible to [connect your data](/article/m8p1kx5f#adding-data), [create dashboards](/article/m8p1kx5f#creating-dashboards), and [embed them](/article/m8p1kx5f#embedding-dashboards) in your application's different environments. 2. You can use one (or multiple) [Collection(s) per environment](/article/m8p1kx5f#embed-group) 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)](/article/m8p1kx5f#deploying-dashboards) from one environment to the next, allowing for easy validation in your application's different development environments before releasing the changes to production.

Tag: staging

Need more information?

Do you still have questions? Let us know how we can help.