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 workbooks. 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 workbooks.

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 Workbook
            [Step 2] Create a Production Copy of your Workbook 
            [Step 3] [optional] Assign Embeds to your Production Workbook
      Folder Structure Best Practices
Copy a Workbook and its Sources
      What gets copied and what doesn’t?
      How To Copy a Workbook and its Sources
Reassign an Embed
Limitations
Recommended Resources

Requirements

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

• Only Admins can create copies of Workbooks and their sources.
• Only Admins can create and/or reassign embeds.

The Development to Production Workflow

What is it?

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

When this workflow is implemented your team will have a single workbook 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 workbooks is a collaborative process. Typically, an organization Creator manages workbook 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 workbook 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 workbook and its sources allows you to point your Public or Application embed to one stable workbook 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 workbook version copies.
• Reassigning embeds allows you to repeatedly repoint your embed to the newest version of the workbook without having to do any work outside of Sigma.
  

Getting Started

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

1. Create or open your workbook. 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 of Development to Production workflow process: 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 workbook embeds should point to the current production version.
   Note: If your original (aka development) workbook already has one or more embeds, reassign each embed to point to the new production workbook 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 Workbook

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

Tips:

• When editing a workbook 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 workbook URL (see Share a Workbook for more information). 
  
  

[Step 2] Create a Production Copy of your Workbook 

To migrate your workbook to production, create a copy of the development Workbook 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 document and folder 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 below.
• Be sure to clearly designate the development version of the workbook and its sources for the next time you want to make changes. 
• If desired, you may swap out the data source(s) of the workbook while creating a new version. Please refer to the copy instructions below for more information. 
• Any existing embeds should be reassigned to your new production version (see #3).|
  
  

[Step 3] [Optional] Assign Embeds to Your Production Workbook

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

Requirements: Only Admins can perform this action.

Tips:

• Important: If you are using application embedding and the new version of your workbook modifies controls, reassigning the embed will break your existing implementation. You should create a new embed URL for this workbook 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 workbook that you manage, we recommend maintaining a single folder and storing all versions of that workbook in that folder.  Version folders can be created during the workbook copy process.

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

Our example uses embeds. Currently, the embed URL points to the workbook 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 workbook copy.

Copy a Workbook and Its Sources

What gets copied and what doesn’t?

The copied workbooks and any underlying datasets are copied and stored in the designated folder.  The underlying documents are automatically stored in a “Dependencies” folder.

In the example below, a Workbook 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.

Note: 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 Workbook and Its Sources

1. Open your existing workbook in Sigma.
   If the Workbook is in edit mode, Publish your changes or Discard your draft.
2. Click theicon in the Workbook header.
3. Select Copy Workbook and Sources from the drop-down menu to open the Copy Workbook and Sources modal.
4. [Optional] You will be given the option to swap out the original data source(s) of the workbook.
   To change your warehouse connection, select the appropriate connection from the Connection drop-down menu.
   To change databases and/or schemas, hover over the level you would like to change and click Modify.
   Note: When swapping data source(s), table names must remain identical to the original source.
   
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.
   
7. Click Create Copy.

It may take a few seconds to create your new deep copy. When copying is complete, you will be redirected to your new workbook. 

Reassign an Embed

Embed reassignment allows you to reassign an existing embed URL to a different workbook or visualization. To reassign an embed, do the following:

1. In the Admin Portal, click the Embed tab to view the list of current embeds for your organization.
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 workbook you would like to use for your embed and click Next.
   Note: If assigning a visualization to the embed, select the workbook specific to the visualization.
   
4. The modal will now prompt you to configure your embed reassignment.
   In the Reassign Embed Path To drop-down menu, select the entire workbook or a single visualization.
   
5. Click Reassign.

Limitations

• Creating copies of Workbooks and their sources is not fully supported for Workbooks built from 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 Workbooks and their sources is not supported if the workbook contains visualizations from multiple warehouse connections. As such, the development to production workflow is not possible.
  
  

Related Resources

Workbook Embedding: An Overview
Application Embedding
Public Embedding
Private Embedding