Dashboard Development to Production Workflow (Beta)

IMPORTANT: This document is specific to Sigma dashboards. To learn about this topic for Sigma’s new Workbooks feature, please visit Workbook Development to Production Workflow (Beta).

Data analytics is a continuous process. As you dive deeper into your data, you will likely want to continually update and build upon existing dashboards. To aid in this process, Sigma has built features and developed a recommended workflow specifically to address development to production needs. The following article documents our recommended workflow and tips. 

This project is currently in a limited beta version. It is also important to note that the initial beta implementation of this feature is focused on support for embedded dashboards.

To request beta access to this feature, please contact your Sigma Account Representative.

Summary of Content

Requirements
The Development to Production Workflow
      What is it?
      Who’s Involved?
      Getting Started
      The  Workflow
            [Step 1] Develop your Dashboard
            [Step 2] Create a Production Copy of your Dashboard 
            [Step 3] [optional] Assign Embeds to your Production Dashboard
      Folder Structure Best Practices
Copy a Dashboard and its Sources
      What gets copied and what doesn’t?
      How To Copy a Dashboard and its Sources
Reassign an Embed
Limitations
Recommended Resources

Requirements

The dashboard development process typically involves collaborating between Creators and Admins. However, certain features used in this process are Admin only:

The Development to Production Workflow

What is it?

The development to production workflow is a controlled means to support continuous development of production-scale dashboards, without releasing in-progress versions to outside audiences.

When this workflow is implemented your team will have a single dashboard for development, alongside a potential series of production versions. The development version will be used for updates, draft review, and approval. Each time updates are published to the development version, an Admin can create a new production version for sharing with a broader audience. 

Who’s Involved?

Developing and deploying production dashboards is a collaborative process. Typically, an organization Creator manages dashboard development. However, an organization Admin is responsible for configuring and managing the resulting production versions. Depending on your team’s use case, this may involve dashboard embedding.

Admins - use the steps list under Getting Started and The Workflow to guide you through the versioning and embed management process. Depending on your team’s use case, you will use one or both of the following Admin features: 

  • Copying a Dashboard and its sources will allow you to point your Public or Application embed to one stable Dashboard while concurrently developing a next-generation version. As you will read below, it is best practice to maintain your original copy for development purposes while simultaneously pointing your embeds to static dashboard version copies.
  • Embed Reassignment will allow you to repeatedly repoint your embed to the newest version of the Dashboard, without having to do any work outside of Sigma.

Getting Started

Do you want to transition a single existing dashboard to use a development to production workflow? The following instructions will help you jump into this process for the first time.

  1. Create or open your dashboard. This will be your development version. You will use this version for all updates.
  2. Make a new copy of your development version. This copied version, and all those that follow, will be your production versions.
    Example: Make changes to your development version ->  publish ->  create a new production copy (v2) -> make changes to your development version  -> publish -> create a new production copy (v3) -> REPEAT.
  3. [optional] All dashboard embeds should point to the current production version.
    If your original (aka development) dashboard already has one or more embeds, reassign each embed to point to the new production dashboard version.
    If you do not already have an embed, create a new embed on your production copy using the following instructions:
    Create an Application embed OR Create a Public embed.
  4. Next Steps: Continue to follow the recommended workflow listed below. 

The Workflow

You can follow this workflow for any number of stages that you may have in your development cycle.

[Step 1] Develop your Dashboard

As needed, update your development dashboard and/or its sources with any desired changes.

Tips:

  • When editing a dashboard or any of its underlying sources, you should always edit the development version, NOT a version copy used for production. 
  • Draft review and approval are common stages of most development processes. We recommend sharing your drafts before you publish. This can be done via the dashboard URL. 

[Step 2] Create a Production Copy of your Dashboard 

To migrate your dashboard to production, create a copy of the development Dashboard and its sources.
Requirements: Only Admins can perform this action. 

Tips:

  • Keep edit permissions limited on your production versions. This can prevent accidental changes from being published. Learn more about permissions.
  • Over time, you will likely accumulate a number of copies. We recommend naming copies by version number and building a consistent folder structure. See folder structure best practices.
  • Be sure to hold onto the development version of the Dashboard and its sources for the next time you want to make changes. 
  • If desired, you may swap out your Dashboard’s origin warehouse data source(s) while creating a new version. Please refer to the copy instructions for more information. 
  • Any existing embeds should be reassigned to your new production version (see #3).

[Step 3] [optional] Assign Embeds to your Production Dashboard

Embeds should always point to the Dashboard’s current production version. Once you have created a  production version of your dashboard, any existing embeds should be reassigned to this new version.

Requirements: Only Admins can perform this action.

Tips:

  • WARNING: If you are using application embedding and the new version of your dashboard modifies controls, reassigning the embed will break your existing implementation. You should create a new embed URL for this dashboard and update the url in your application.
  • New to embeds?  Create an Application embed OR Create a Public embed.

Folder Structure Best Practices

Version organization is increasingly important as your version history grows. For each embedded dashboard that you manage, we recommend maintaining a single folder and storing all versions of that dashboard in that folder.  Version folders can be created during the dashboard copy process.

The screenshot below shows the top level view of this folder structure. The “Development” folder contains the development version of the Dashboard. And each version numbered “Production” folder contains a copy of the dashboard and a dependencies folder.

Our example uses embeds. Currently, the embed URL points to the dashboard copy in “Production v3”. The next time a Creator decides to make changes, they will edit the development version and/or its sources. After it passes review and is published, an organization Admin will create a new copy in a new folder titled “Production v4”. They will then reassign the embed URL to the new v4 dashboard copy.
Screen_Shot_2020-11-02_at_4.41.49_PM.png


Copy a Dashboard and its Sources

What gets copied and what doesn’t?

The copied dashboard and any underlying worksheets and datasets are all copied and stored in your designated folder. The underlying documents are automatically stored in a “Dependencies” folder.
In the example below, a Dashboard copy named “Sales Trends - Production v2” was created in the “Production v2” folder. The dependencies folder, “Sales Trends - Production v2 (Dependencies)”, was automatically saved in the same folder.

Screen_Shot_2020-11-02_at_4.35.39_PM.png

 

Underlying Tables, folder structure, report schedules, existing embeds, document permissions, and Dataset Materialization schedules ARE NOT passed on to new copies. 

How To Copy a Dashboard and its Sources

  1. Open your existing dashboard in Sigma.
    If the Dashboard is in edit mode, Publish your changes or Discard your draft. . 
  2. Click the ••• menu icon in the Dashboard header.
  3. Select Copy Dashboard and Sources from the dropdown menu to open the Copy Dashboard and Sources Modal.
  4. [optional] You will be given the option to swap out your dashboard’s origin warehouse data source(s).
    To change your warehouse connection, connection dropdown menu.
    To change databases and/or schemas, hover over the level you would like to change and click Modify.
    When swapping data sources, table names must remain identical to the original source.
    Screen_Shot_2020-11-02_at_2.02.15_PM.png
  5. When you are ready, click Next.
  6. You will now be prompted to name your copy and select its folder path destination.
    To create a new folder, click the Create Folder button in the modal footer.
    Read about folder structure best practices for embed versioning.
    Screen_Shot_2020-11-02_at_4.15.24_PM.png
  7. Click Create Copy.
  8. It may take a few seconds to create your new deep copy. When copying is complete, you will be redirected to your new dashboard. 

Reassign an Embed

Embed reassignment allows you to reassign an existing embed URL to a different dashboard or visualization. To reassign an embed:

  1. Find the embed in your Admin Portal embed list.
  2. Click the ••• menu icon to the right of the embed you would like to reassign.
    This will open the Reassign Embed modal.
  3. Select the dashboard you would like to use for your embed and click Next.
    If assigning a visualization to the embed, select the visualization’s dashboard.
    Screen_Shot_2020-11-02_at_4.22.58_PM.png
  4. The modal will now prompt you to configure your embed reassignment.
    Under Reassign embed path to, select the entire dashboard or a single visualization.
    Screen_Shot_2020-11-02_at_5.16.27_PM.png
  5. Click Reassign.

Limitations

  • Creating copies of Dashboards and their sources is not fully supported for Dashboards built off CSV data sources, as the process may require additional per-case user intervention. Please contact Sigma support with any questions or concerns.
  • Creating copies of Dashboards and their sources is not supported if the dashboard contains visualizations from multiple warehouse connections. As such, the development to production workflow is not possible.

Related Resources

Sigma Embedding: An Overview
Application Embedding
Public Embedding
Embed Management

 

IMPORTANT: This document is specific to Sigma dashboards. To learn about this topic for Sigma’s new Workbooks feature, please visit Workbook Development to Production Workflow (Beta).