Documentation
HomeCommunityQuickStartsStatus

Update a workbook from a code representation (Beta)

🚩

This documentation describes one or more private beta features that are in development. Beta features are subject to quick, iterative changes; therefore the current user experience in the Sigma service can differ from the information provided in this page.

This page should not be considered official published documentation until Sigma removes this notice and the beta flag on the corresponding feature(s) in the Sigma service. For the full beta feature disclaimer, see Beta features.

If you are interested in joining a limited test group and enabling this feature in your Sigma organization, contact Support or reach out to your Account Executive.

You can update an existing workbook from a code representation by calling the Update a workbook from a code representation endpoint with the code representation in the request body.

This document provides step-by-step instructions for using this endpoint to update a workbook from a code representation. For more information on working with workbooks programmatically, see Manage workbooks as code.

User requirements

The ability to update a workbook from a code representation requires the following:

  • You must have developer credentials for the Sigma API. For more information, see Get started with the Sigma REST API.
  • The user associated with your API credentials must be assigned an account type with the Create, edit, and publish workbooks permission enabled.
  • You must be the document owner or be granted Can edit access to the workbook.

Generate API client credentials and an API access token

To start, you must generate credentials for the Sigma API. These credentials are used to retrieve an access token, which is required to make requests to the API.

For step-by-step instructions on generating developer credentials in Sigma and using them to authenticate to the Sigma API, see the instructions in Generate client credentials.

Identify the workbook and retrieve the workbookId

To update an existing workbook from a code representation, you must know the unique workbookId for that workbook. After you identify the workbook you want to update, you can call the List workbooks endpoint to retrieve the workbookId:

  1. Go to your Home page.

  2. In the navigation menu, select Documents.

  3. Click the Document type filter and select Workbooks.

    The list of your workbooks appears.

  4. Identify the workbook you want to update, by name, owner, or other details.

  5. Make a GET request to the List workbooks endpoint like the following:

    List workbooks request format
    curl --request GET \
     --url <base_url>/v2/workbooks \
     --header 'Authorization: Bearer <access_token>' \
     --header 'accept:application/json' \
     --header 'content-type: application/x-www-form-urlencoded'

    The response includes a list of workbooks in your organization, in the following format:

    List workbooks response format
    {
  "entries": [
    {
      "workbookId": "<workbookId>",
      "workbookUrlId": "<workbookUrlId>",
      "createdBy": "<userId>",
      "updatedBy": "<userId>",
      "createdAt": "<timestamp>",
      "updatedAt": "<timestamp>",
      "name": "<workbookName>",
      "url": "<workbookUrl>",
      "path": "<folderPath>",
      "latestVersion": "<versionNumber>",
      "ownerId": "<userId>"
    },
    {
      "workbookId": "<workbookId>",
      "workbookUrlId": "<workbookUrlId>",
      "createdBy": "<userId>",
      "updatedBy": "<userId>",
      "createdAt": "<timestamp>",
      "updatedAt": "<timestamp>",
      "name": "<workbookName>",
      "tags": [
        {
          "versionTagId": "<versionTagId>",
          "name": "<tagName>",
          "taggedWorkbookId": "<workbookId>",
          "workbookTaggedAt": "<timestamp>",
          "sourceWorkbookVersion": "<versionNumber>"
        }
      ],
      "url": "<workbookUrl>",
      "path": "<folderPath>",
      "latestVersion": "<versionNumber>",
      "ownerId": "<userId>"
    }
  ],
  "hasMore": <boolean>,
  "total": <number>,
  "nextPage": null
}

  6. Identify the workbook you want to update, and copy the workbookId to use with the Update a workbook from a code representation endpoint.

Prepare the representation

To update an existing workbook from a code representation, you must prepare a valid code representation of the workbook with the updates you want to apply. You can base this on the existing workbook's representation, or construct an entirely new one.

🚩

The Update a workbook from a representation endpoint does not support partial updates. To update a workbook, you must provide a complete representation of the workbook, even if you are only making minor changes. Sigma recommends retrieving the existing representation and basing your changes on that.

The code representation you prepare can be passed into the request body of the Update a workbook from a representation endpoint to update the workbook.

  1. Using the workbookId you identified in the previous section, follow the instructions in Retrieve the code representation to get the current representation.

    For example, you might retrieve the representation for a workbook with a single table, like the following:

    YAML representation
    name: table
schemaVersion: 1
pages:
- id: jgZnqiZGOh
    name: Page 1
    elements:
    - id: z8NmRPjbEN
        kind: table
        source:
        connectionId: 6944db1a-f9f0-496f-91ba-4781e7f0490d
        kind: warehouse-table
        path:
            - FUN
            - BIKES
            - TRIP
        columns:
        - id: Y3BEzKB09f
            formula: '[TRIP/Id]'
        - id: qQ09VyFetR
            formula: '[TRIP/Duration]'
        - id: n2weGZ6GfF
            formula: '[TRIP/Start Date]'
        - id: jWEvA87YUH
            formula: '[TRIP/Start Station Name]'
        - id: D8c5YVgpsZ
            formula: '[TRIP/Start Station Id]'
        - id: r3pku8OHAS
            formula: '[TRIP/End Date]'
        - id: fjSITWU8RE
            formula: '[TRIP/End Station Name]'
        - id: rsndxYRmfw
            formula: '[TRIP/End Station Id]'
        - id: ujOO9jaUuB
            formula: '[TRIP/Bike Id]'
        - id: vQL0WpcDi6
            formula: '[TRIP/Subscription Type]'
        - id: 8nEosRvuru
            formula: '[TRIP/Zip Code]'
        order:
        - Y3BEzKB09f
        - qQ09VyFetR
        - n2weGZ6GfF
        - jWEvA87YUH
        - D8c5YVgpsZ
        - r3pku8OHAS
        - fjSITWU8RE
        - rsndxYRmfw
        - ujOO9jaUuB
        - vQL0WpcDi6
        - 8nEosRvuru
layout: |
<?xml version="1.0" encoding="utf-8"?>
<Page type="grid" gridTemplateColumns="repeat(24, 1fr)" gridTemplateRows="auto" id="jgZnqiZGOh">
    <LayoutElement elementId="z8NmRPjbEN" gridColumn="1 / 25" gridRow="1 / 21"/>
</Page>

  2. Make any desired changes to the representation. For example, you might want to rename the workbook, rename a table, or add a new column.

🚩

The workbook code representation does not support all workbook features. Unsupported features are silently dropped when you make a request to the Get the code representation of a workbook endpoint. If you use a representation from that endpoint to create or update another workbook from code, it does not include the dropped features, even if they were present in the original workbook.

In this example, most columns are removed from the representation, leaving only the Id and Duration:

YAML representation
name: table
schemaVersion: 1
pages:
- id: jgZnqiZGOh
    name: Page 1
    elements:
    - id: z8NmRPjbEN
        kind: table
        source:
        connectionId: 6944db1a-f9f0-496f-91ba-4781e7f0490d
        kind: warehouse-table
        path:
            - FUN
            - BIKES
            - TRIP
        columns:
        - id: Y3BEzKB09f
            formula: '[TRIP/Id]'
        - id: qQ09VyFetR
            formula: '[TRIP/Duration]'
        order:
        - Y3BEzKB09f
        - qQ09VyFetR
layout: |
<?xml version="1.0" encoding="utf-8"?>
<Page type="grid" gridTemplateColumns="repeat(24, 1fr)" gridTemplateRows="auto" id="jgZnqiZGOh">
    <LayoutElement elementId="z8NmRPjbEN" gridColumn="1 / 25" gridRow="1 / 21"/>
</Page>

Call the Update a workbook from a code representation endpoint

Finally, call the Update a workbook from a code representation endpoint, passing the workbookId as a path parameter and the updated code representation in the request body. The request format is as follows:

Update a workbook from a representation request format
curl --request PUT \
    --url <base_url>/v2/workbooks/<workbookId>/spec \
    --header 'Authorization: Bearer <access_token>' \
    --header 'content-type: application/json' \
    --data '<representation>'

This example request replaces the example representation shown after step 1 of the previous section with the truncated representation from step 2:

Update a workbook from a representation request example
curl --request PUT \
    --url <base_url>/v2/workbooks/<workbookId>/spec \
    --header 'Authorization: Bearer <access_token>' \
    --header 'content-type: application/yaml' \
    --data 'name: table
schemaVersion: 1
pages:
- id: jgZnqiZGOh
    name: Page 1
    elements:
    - id: z8NmRPjbEN
        kind: table
        source:
        connectionId: 6944db1a-f9f0-496f-91ba-4781e7f0490d
        kind: warehouse-table
        path:
            - FUN
            - BIKES
            - TRIP
        columns:
        - id: Y3BEzKB09f
            formula: "[TRIP/Id]"
        - id: qQ09VyFetR
            formula: "[TRIP/Duration]"
        order:
        - Y3BEzKB09f
        - qQ09VyFetR
layout: |
<?xml version="1.0" encoding="utf-8"?>
<Page type="grid" gridTemplateColumns="repeat(24, 1fr)" gridTemplateRows="auto" id="jgZnqiZGOh">
    <LayoutElement elementId="z8NmRPjbEN" gridColumn="1 / 25" gridRow="1 / 21"/>
</Page>
'

The endpoint updates the workbook with the new representation.

Resources
Sigma home
Blog
Learn
Sigma Community
© Sigma Computing