Tag a workbook

POST

/v2/workbooks/tag

POST

/v2/workbooks/tag

curl -X POST https://api.sigmacomputing.com/v2/workbooks/tag \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "workbookId": "12345678910",
  "tag": "production",
  "workbookVersion": 4,
  "sourceMappingConfig": [
    {
      "fromConnectionId": "00000000-0000-0000-0000-000000000000",
      "toConnectionId": "00000000-0000-0000-0000-000000000001",
      "paths": [
        {
          "fromPath": [
            "SNOWFLAKE_DEVELOPMENT",
            "WEATHER",
            "DAILY_14_TOTAL"
          ],
          "toPath": [
            "SNOWFLAKE_PRODUCTION",
            "WEATHER",
            "DAILY_16_TOTAL"
          ]
        }
      ]
    }
  ],
  "sourceVersions": {
    "<datasetId>": 2
  },
  "isDefault": true
}'

200Request Example

{
  "versionTagId": "string",
  "taggedWorkbookId": "string",
  "taggedWorkbookVersion": 1.1
}

Add a version tag to a workbook and optionally set up a connection to swap to for a specific version of the workbook.

Usage notes

Retrieve the workbookId by calling the /v2/workbooks endpoint.
Retrieve the tag by calling the /v2/tags endpoint and using the name in the response.
Retrieve the connectionId to use as the fromId or toId by calling the /v2/connections endpoint.
If your workbook includes a source that is not mapped to a new source, that source is not swapped.
When swapping data models used as the source for the workbook:
- You can only swap a data model source to another version of the same data model source. You cannot swap a data model source to a table in your data warehouse or a dataset.
- When you swap sources from one data model version to a new one, specify the version tag of the data model that you swap to with toVersionTagId:
  - To swap to the latest published version of the data model, specify toVersionTagId as null.
  - To swap to a specific tagged version of the data model, specify the toVersionTagId of the data model.
- If the workbook already uses a specific tagged version of a data model as a source, use fromVersionTagId to indicate which tagged version to swap from.
  - To swap from the latest published version of the data model, specify fromVersionTagId as null.
  - To swap from a specific tagged version of the data model, specify the fromVersionTagId of the data model.
To retrieve the fromVersionTagId for a data model used as the workbook source, call the /v2/workbooks/{workbookId}/sources endpoint and use the versionTagId in the response.
To retrieve the versionTagId for a data model, call the /v2/dataModels endpoint and use the versionTagId in the response.

Usage scenarios

Lifecycle management: Identify production and development resources.

Authentication

AuthorizationBearer

OAuth authentication of the form <token>.

Request

The request body.

workbookIdstringRequired

Unique identifier of the workbook.

tagstringRequired

Name of the version tag to apply.

workbookVersiondoubleOptional

Specific version of the published workbook to tag.

sourceMappingConfiglist of objectsOptional

Swap sources for the workbook when you add a tag.

dataModelSourceTaggedVersionslist of objectsOptional

Which tagged version of the data model to use as the source.

sourceVersionsmap from strings to doublesOptional

Which version of source datasets to use.

grantSourceAccessbooleanOptional

Whether to grant users access to copied datasets if they create a copy via Save As.

isDefaultbooleanOptional

Whether to make this tag the default tagged version to load if the user doesn't have access to the published version.

Response

The response body.

versionTagIdstring

taggedWorkbookIdstring

Unique identifier of the workbook.

taggedWorkbookVersiondouble