Version Tagging

This document explains how to create and use tags to control workbook versions. 

Contents

Requirements
Introduction
Create a Tag
     Tagged Workbook URLs
     View Tags
Add a Tag to a Workbook
Publish a Draft to a Tagged Workbook
Select a Dataset Version
Swap the Connection Path
Select an Existing Tag
Share a Tagged Workbook
Related Resources

Requirements

• Admin to create the tag
• Edit to tag a workbook

Introduction

Version tagging allows you to employ a software development cycle to control workbook versions using tags. For example, orgs can have a development, staging, and production version of a workbook and migrate changes as needed. This allows you to control which workbook versions are viewable by your users. 

When you create a tag and assign it to a workbook, you essentially freeze the state of that workbook. The process of tagging a workbook creates a duplicate that can be shared with other stakeholders and users.  

For example, you can create a Production tag and assign it to a workbook that's used by embed users, guests, or other Sigma end users. Moreover, you can tag additional versions of the same workbook such as Development or Staging. These versions can be used by different stakeholders in your org for review purposes. Once reviewed, you can migrate this copy to Production for your users. 

One of the benefits of this solution is your org can modify a Development workbook without affecting the experience of your customers who use the Production version. Once you complete your developmental changes, you can easily update the Production version of the workbook.

Create a Tag

Follow the steps below to create a tag.

1. As an admin, go to the Admin portal and click Tags. 
2. Click Create Tag. 
3. Enter a Name and Description for your tag. These values should correspond to how you intend to use the tag. 
   

   The tag name must be unique. It's not case sensitive.

4. Select a color for your tag.
    
   

   
   
   

5. Click Create.

Tagged Workbook URLs

When you create a tag, the name of the tag is added to a workbook URL as a suffix. In the example below, a staging tag is added to the end of the URL. You can access the staging version by adding staging to the end of the workbook URL. 

/workbook/My-Workbook-{workbook_id}/tag/staging

This logic also applies to embeds. The staging tag is added to the URL as a suffix and allows the user to call that specific version of the workbook. 

/embed/{embed_id}/tag/staging

View Tags

On the Tags tab, you can view a complete list of the tags created in your org. In the Tag Name column, you can click on any workbook to open and view it. The Workbooks Using column displays the number of workbooks with that tag. 

Add a Tag to a Workbook

The workbook must be in a published state in order to add a version tag. 

1. Open or create a workbook.
2. Click on the caret next to the workbook name. 
3. Click Tag this published version. 
   
   
   
4. In the Choose Tag field, select a tag. 
   
   
   
   
5. Check Allow saving as a new workbook if you want to grant Can View permission to all sources used, if the user has permissions for the workbook. If this option is selected, the user can choose Save As option.  
6. Check Swap sources of the tagged version to select a different source (connection, database, schema) for this tagged workbook. You can browse and select available sources in the dropdown under Sources of Tagged Workbook. Click Swap and tag. 
   
   

Publish a Draft to a Tagged Workbook

When you publish a workbook, it can be used as your development version. The Published version of a workbook is where your org can modify a workbook, eventually migrate to Production and make available to your users.  

Follow the steps below to push workbook changes to tagged workbooks. 

1. Open the published workbook that you want to promote to Production, or any version.  
   

   No user type can make changes to tagged workbooks.

2. Click Edit and make desired changes to the workbook. 
3. Publish the changes. 
4. Click the Workbook dropdown and select Tag latest published version or Tag this published version (if there are no previous versions).
   
   
    
   
   
5. In the Choose Tag field, select the appropriate tag.
   

   You are essentially tagging the Published workbook, which replaces the previously published workbook version. For example, if you add a Production tag to the published workbook, the previous content of the Production workbook is removed and replaced.

   
   
6. Check Allow saving as a new workbook if you want to grant Can View permission to all sources used, if the user has permissions for the workbook. If this option is selected, the user can choose Save As option.  
7. Check Swap sources of the tagged version to select a different source (connection, database, schema) for this tagged workbook. You can browse and select available sources in the dropdown under Sources of Tagged Workbook. Click Swap and tag. 
8. Click Set Tag.
9. Users can refresh the workbook to see the new changes. 

Select Dataset Version

If you follow the steps above to tag a workbook, but the workbook uses datasets as a source, a different modal appears.

In the Datasets Used in Workbooks field, Dataset A & B default to the current version.  You can click the dropdown to browse and select older versions of the datasets to use as a source for a tagged workbook. 

Swap the Connection Path

To swap a connection path for a tagged workbook, first follow the steps above to tag the workbook. You can also tag the workbook in the Choose Tag field. 

1. Check Swap sources of the tagged version and click Set Tag.

   

2. In the Modify sources modal, click on the dropdown under Sources of Tagged Workbook to change the database. 
   
3. Click Set Tag.
4. Click Modify to browse and select database or schema.
   
   
   
   
5. Once you click Modify, you can browse and select an available source. Click Confirm to save your change. 
   
    
6. Click Swap and Tag. 

Select an Existing Tag

Once your org has created tags, you can browse a list of tags from a workbook. To browse tags from a workbook:

1. Open or create a workbook. 
2. Click the Production label at the top of the workbook.
   
   
   
   
3. Select a tag to add to the workbook. 

Share a Tagged Workbook

Follow the steps below to share a tagged version of a workbook. For a detailed explanation on how to share workbooks, see Share a Workbook.

1. Go to the share modal.
2. Under the Share modal's Share tab, select the team or organization member with whom you would like to share the tagged workbook. 
   

   When you hover over a Permission, you can select an individual tag, or All tags, in the Tags column.

   
   
3. Click Save.