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
Apply a Tag to a Workbook
Request Protected Tag Applied to Workbook
Publish a Draft to a Tagged Workbook
Select a Dataset Version
Swap the Connection Path
Select an Existing Tag
Share a Tagged Workbook
Input tables
Related Resources

Requirements

• To create Public tags, you must have Can edit permissions on the workbook
• To create Protected tags, you must be an Admin or have Can edit permissions for the workbook. The member must also be selected in the Search field or be a member of a selected team.
• To request that a tag be applied to a workbook, the workbook must be shared with the requestor and they must have Can edit permissions.  

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. When you create a tag, you can select a permission level: Public or Protected. Protected tags allow you to restrict access & select the users or teams that can apply a tag on a workbook.

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. You can define which users who can apply the tag by selecting Protected. 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 to consume. 

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. Select a Permission.
   
   • Public - To use a tag with Public permissions, the member must have Can edit permissions for the workbook.
   • Protected - To use a tag with Protected permissions, the member must be an admin or have Can edit permissions for the workbook. The member must also be selected in the Search field or be a member of a selected team. 

   If you share the tag with a team, members with Can edit permissions for the workbook can use the tag. Team members with Can view can't use the tag. (This includes all members with a Viewer account type).

   

6. Click Create.
7. After you create the tag, you can view the teams and individuals who can access the tag in the Permissions field. In the field below, you can view the list of workbooks with this tag.  
   

   

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. 

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

Request protected tag applied to a workbook

Users without permission to use a protected tag can submit a request to set that tag on a specific workbook version.

Requester

Follow the steps below to submit a request to apply a tag on a specific workbook version. When a request is made, an email is sent to all the members with access to the protected tag. 

1. Open the workbook and click the caret in the header.
2. Click Tag this published version in the dropdown. 
3. In the Choose Tag field, select the tag you want to request.  
4. In the Why are you requesting to set this tag? field, enter the message you want to include in the email request.  
5. Click Request Tag on Version. This sends an email to members that can approve the request. 

Approver

After the request is made, an email is sent to all the members with explicit access to the protected tag. 

Follow the steps below to approve a request and apply a tag.

1. Open the email. 
2. Click Respond To The Request.
   
   
3. The link opens the workbook version that the user requested the tag to be applied to.
   
   
4. To apply the requested tag, click on the more menu and select Set tag on this version.
   
    
   
   
5. Select and apply the tag. 

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.

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 data source. 
   
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. 

Input tables

Tags can also be used on input tables. When you tag a workbook with input tables, the structure of the input table is copied over without any of the data. Setting a tag creates an independent version of any input table in this workbook. To include the current data in your input table, manually copy & paste the data after you apply the tag.

Follow the instructions below to apply a tag to a workbook with input tables. 

1. On a workbook with input tables, click the caret in the header and click Tag this published version in the dropdown. 
2. Click Ok to acknowledge the informational modal (discussed above).
3. In the Choose Tag field, select the appropriate tag. Check Swap sources of tagged version to change the data source.  
   
   
4. Click Set Tag.
5. In the Sources of Tagged Workbook field, select a new data source.
6. Click Swap and tag.