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

    company apps

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

    company apps

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 on any workbook to open and view it. The Workbooks Using column displays the number of workbooks with that tag.ย 

company apps

Apply a Tag to a Workbook

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

๐Ÿ“˜

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 on the caret next to the workbook name.ย 
  3. Click Tag this published version.ย 
    company apps
  4. In the Choose Tag field, select a tag.ย 
    company apps
  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.ย 
    company apps

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.

๐Ÿ“˜

The workbook must be shared with the requestor and they must have Can edit permissions. If they don't they won't see the option to Tag this published version.

  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.ย 
company apps

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.
    company apps
  3. The link opens the workbook version that the user requested the tag to be applied to.
    company apps
  4. To apply the requested tag, click on the more menu and select **Set tag on this version.
    **ย company apps
  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.

๐Ÿ“˜

To share a workbook, you must have Can edit access to the 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.

    ๐Ÿ“˜

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

    company apps

  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).
    company apps

  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.

    company apps

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

Example Use Case:
You may swap data sources if you think a different source contains recent or valid data.ย 

company apps

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

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

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

    company apps

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

  3. Click Set Tag.

  4. Click Modify to browse and select database or schema.
    company apps

  5. Once you click Modify, you can browse and select an available source. Click Confirmย to save your change.ย 
    company apps

  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.
    company apps
  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. ย 
    company apps
  4. Click Set Tag.
  5. In the Sources of Tagged Workbook field, select a new data source.company apps
  6. Click Swap and tag.