Once your dashboard is embedded, you will likely want to iteratively improve the designs of your dashboards.

You can use our version history and publishing feature to control which version of a dashboard will be shown in your application.

You can use Collections or dashboard ids in your embed tokens to control which dashboards will be shown to the user.

Control which version of a dashboard is shown via version history

You can decide which dashboard version you want to show in your application by marking a certain version as the published version in our editor: more information about this can be found in this and this Academy article.

Dashboards can be published to specific environments—such as production, development, or acceptance. By default, the production environment is used. The embedded version of the dashboard will reflect the version published to that environment. This allows you to make changes in the dashboard editor without affecting the live version. Once you're ready, publish the updated version to the desired environment. If a certain environment does not exist, it will show the latest. Additionally, it is possible to use the securableVersion API endpoint to check is a version is tagged with a certain environment.

Control which dashboard is shown

The authorization token you create for a user determines to which resources they will have access to. You can give access to specific Collections, or to specific dashboards/datasets.

You can thus decide to control which dashboards a user will see in a certain environment by one of following methods:

1. Create a Collection per environment
2. Retrieve a list of dashboards and datasets per environment based on tags
3. Have a list of dashboards and datasets per environment in your code base

Create a Collection per environment

This approach is the easiest to set up, can be used in conjunction with dashboard versioning / publishing and is advisable to be able to release new dashboards without help from the engineering team.

To control which dashboards are shown in which environemnt, you could opt to create separate Collections by environment (e.g. production, development).

This allows you to add/replace/remove dashboards in the development environment(s) without influencing the production environment, all from within our UI!

Transitioning between environments is then as simple as referencing the corresponding collection id in the authorization request in your application's backend.

Retrieve dashboards and datasets via Tags

This approach is advisable to be able to release to new dashboards without help from the engineering team. It is however less scalable then the approach with a Collection per environment as you need to duplicate dashboards instead of being able to use the dashboard versioning and publishing feature.

You can assign tags to your dashboards and datasets. You can then dynamically retrieve a list of dashboards & datasets with a certain tag to add them to the authorization token.

1. First duplicate a production dashboard, then start adapting it.
2. Once satisfied with your changes, add the Production tag to the dashboard.
3. Remove the Production tag from your previous dashboard.
4. Because the dashboard inuse is dynamically determined, the change is live immediately.

You can use the Core API 'Tag' entity to retrieve dashboards by tag:

client.get('tag', {
    where: {
        tag: '< your tag name >'
    },
		include: [
        {
            model: 'Securable',
            attributes: ["id", "name"],
            jointype: "inner"
        }
    ]
})

Or you can use the Core API 'Securable' entity to retrieve dashboards and datasets by tag:

client.get('securable', {
	attributes: ["id", "name"],
	include: [
		{
			model: 'Tag',
			where: {
				tag: '< your tag name >'
			},
			attributes: ["id", "tag"],
			jointype: "inner"
		}
	]
})

To retrieve dashboards based on multiple tags:

client.get('securable', {
	attributes: ["id", "name"],
	include: [
		 {
			 model": "Tag",
			 where: {
					tag: {
						in: [
							"< your tag name >",
							"< your tag name >",
							...
						]
					}
				},
			jointype: "inner"
		}
	]
})

List of dashboards and datasets per environment in your code base

This approach is advisable if you want to tightly embed with your regular CI/CD (continuous integration / continuous delivery) flows. It is however less scalable then the approach with a Collection per environment as you need to duplicate dashboards instead of being able to use the dashboard versioning and publishing feature.

• First duplicate a production dashboard, then start adapting it.
• Once satisfied with your changes, you can commit the new dashboard ID (and dataset IDs) to your code or configuration.
• A new build & deploy of your code base will change the dashboard in use.
• If the new dashboard is breaking for some reason, you can roll back your change. Your code will then point to the previous (unchanged) dashboard again.