Version tagging

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

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 streamline your workbook development cycle using tags to manage, control, and organize workbook iterations. For example, your organization can utilize Development, Staging, and Production version tags to develop workbooks, migrate changes as needed, and control which versions are accessible to specific 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 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 organization 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. 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

📘

To access a tagged workbook, users must be granted access to the workbook or be the workbook's editor.

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

To apply a tag to a workbook, follow these steps.

📘

To apply a protected tag, you must be an Admin or have Can edit permissions for the workbook and be selected in the Search field or be a member of a selected team.

1. Open or create a workbook.

2. Click 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 user to use data sources when they "Save as" 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 Save As option without errors.  

6. Check Swap sources of the tagged version to select a different source (connection, database, schema) for this tagged workbook. See Swap the source of a tagged version.

7. Check Set this tag as default to load this tagged version of the workbook for all users who do not have access to the Published version of the workbook, but who do have access to this tag. See Set a default tag for a workbook.

8. Click Set Tag.

Set a default tag for a workbook

When you apply a tag to a workbook, you have the option of setting it as the default tag. The default tag determines what version of a workbook is displayed by default to a user who does not have access to the Published version. If a user does have access to the Published version, the Published version takes precedence over the default tag.

📘

Workbooks that have no default tag set load the latest created tag that the user has access to, if the user does not have access to the Published version of the workbook.

Any user with edit access to the workbook can override a default tag by setting a different tag as the default. If the tag is protected, only users with access to the protected tag can set that tag as the default.

To remove a tag as default without replacing it with a different default tag, follow these steps:

1. Click the caret () next to the version name.

2. Click View version history.

3. Click More next to the default version tag.

4. Click Remove as default.

   

Request a protected tag be 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

To submit a request to apply a tag on a specific workbook version, use the following steps.

📘

To submit a request, the workbook must be shared with you and you must have Can edit permissions. If you don't have those permissions on the workbook, you do not see the option to Tag this published version.

1. Open the workbook and click the caret () next to the workbook name.

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, Sigma sends an email 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 with the version history open.
   

4. To apply the requested tag, click Approve.

5. In the Set Tag on Version modal, make any necessary adjustments. See Apply a tag to a workbook.

The requestor receives an email notifying them that their request was approved or denied.

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.

📘

To share a workbook, you must have Can edit access to the workbook.

1. Click Share in the workbook header. The Share Workbook modal appears.

2. Search or browse to find the team or organization member with whom you would like to share the tagged workbook.

3. Hover over a permission to select an individual tag, or All tags, to share.

   

4. Click Share.

Publish a draft to a tagged workbook

When you tag a workbook, it can be used as your development version. The development version of a workbook is where your org can modify a workbook and then eventually migrate it to production and make it available to end users.  

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

1. Open the published workbook that you want to promote to a tag, 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 caret () next to the workbook name 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 user to use data sources when they "Save as" 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 Save As option without errors.  

7. Check Swap sources of the tagged version to select a different source (connection, database, schema) for this tagged workbook. See Swap the source of a tagged version.

8. Check Set this tag as default to load this tagged version of the workbook for all users who do not have access to the Published version of the workbook, but who do have access to this tag. See Set a default tag for a workbook.

9. Click Set Tag.

10. Users can refresh the workbook to see the new changes.

Select dataset version

If you follow the steps to apply a tag to 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.

You can also swap data sources if you think a different source contains recent or valid data.

Swap the source of a tagged version

To select a different connection path, database, or schema for a tagged workbook, first follow the steps to apply a tag to a workbook.

📘

If a tagged workbook has a CSV, you can't swap the connection source.

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

   

2. In the Modify sources modal, click the dropdown under Sources of Tagged Workbook to change the data source.
   

3. Click Modify to browse and select a database or schema.
   

4. After you click Modify, you can browse and select an available source. Click Confirm to save your changes.

5. Click Swap and tag.

Version tags with 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 and paste the data after you apply the tag.

Version tagging in embeds

In an embedded environment, you can use version tagging to manage promoting content between environments, but you might also want the ability to leverage the source control platforms already integrated in your development workflow, such as GitHub or Bitbucket. You can do so with Sigma's REST API and third-party control systems.

For a guided tutorial, see QuickStart - Embedding 08: Version Tagging.