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:

Go to your Home page.
In the navigation menu, select Documents.
Click the Document type filter and select Workbooks.

The list of your workbooks appears.
Identify the workbook you want to update, by name, owner, or other details.

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

1 {
2   "entries": [
3     {
4       "workbookId": "<workbookId>",
5       "workbookUrlId": "<workbookUrlId>",
6       "createdBy": "<userId>",
7       "updatedBy": "<userId>",
8       "createdAt": "<timestamp>",
9       "updatedAt": "<timestamp>",
10       "name": "<workbookName>",
11       "url": "<workbookUrl>",
12       "path": "<folderPath>",
13       "latestVersion": "<versionNumber>",
14       "ownerId": "<userId>"
15     },
16     {
17       "workbookId": "<workbookId>",
18       "workbookUrlId": "<workbookUrlId>",
19       "createdBy": "<userId>",
20       "updatedBy": "<userId>",
21       "createdAt": "<timestamp>",
22       "updatedAt": "<timestamp>",
23       "name": "<workbookName>",
24       "tags": [
25         {
26           "versionTagId": "<versionTagId>",
27           "name": "<tagName>",
28           "taggedWorkbookId": "<workbookId>",
29           "workbookTaggedAt": "<timestamp>",
30           "sourceWorkbookVersion": "<versionNumber>"
31         }
32       ],
33       "url": "<workbookUrl>",
34       "path": "<folderPath>",
35       "latestVersion": "<versionNumber>",
36       "ownerId": "<userId>"
37     }
38   ],
39   "hasMore": <boolean>,
40   "total": <number>,
41   "nextPage": null
42 }

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 code 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 code representation endpoint to update the workbook. The body must include the document object with its required schemaVersion, kind, elements, pages, and layout fields.

Whenever you add or remove an element, update the layout to match. Every element in document.elements must be placed in the layout, and a representation with an element the layout never references is rejected with an error naming that element, such as elements[0]: element 'z8NmRPjbEN' is not placed in layout.

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

1 name: table
2 document:
3   schemaVersion: 1
4   kind: workbook
5   elements:
6     - id: z8NmRPjbEN
7       kind: table
8       source:
9         connectionId: 6944db1a-f9f0-496f-91ba-4781e7f0490d
10         kind: warehouse-table
11         path:
12           - FUN
13           - BIKES
14           - TRIP
15       columns:
16         - id: Y3BEzKB09f
17           formula: '[TRIP/Id]'
18         - id: qQ09VyFetR
19           formula: '[TRIP/Duration]'
20         - id: n2weGZ6GfF
21           formula: '[TRIP/Start Date]'
22         - id: jWEvA87YUH
23           formula: '[TRIP/Start Station Name]'
24         - id: D8c5YVgpsZ
25           formula: '[TRIP/Start Station Id]'
26         - id: r3pku8OHAS
27           formula: '[TRIP/End Date]'
28         - id: fjSITWU8RE
29           formula: '[TRIP/End Station Name]'
30         - id: rsndxYRmfw
31           formula: '[TRIP/End Station Id]'
32         - id: ujOO9jaUuB
33           formula: '[TRIP/Bike Id]'
34         - id: vQL0WpcDi6
35           formula: '[TRIP/Subscription Type]'
36         - id: 8nEosRvuru
37           formula: '[TRIP/Zip Code]'
38       order:
39         - Y3BEzKB09f
40         - qQ09VyFetR
41         - n2weGZ6GfF
42         - jWEvA87YUH
43         - D8c5YVgpsZ
44         - r3pku8OHAS
45         - fjSITWU8RE
46         - rsndxYRmfw
47         - ujOO9jaUuB
48         - vQL0WpcDi6
49         - 8nEosRvuru
50   pages:
51     - id: jgZnqiZGOh
52       name: Page 1
53   layout: |
54     <?xml version="1.0" encoding="utf-8"?>
55     <Page type="grid" gridTemplateColumns="repeat(24, 1fr)" gridTemplateRows="auto" id="jgZnqiZGOh">
56       <Element elementId="z8NmRPjbEN" gridColumn="1 / 25" gridRow="1 / 21"/>
57     </Page>

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

1 name: table
2 document:
3   schemaVersion: 1
4   kind: workbook
5   elements:
6     - id: z8NmRPjbEN
7       kind: table
8       source:
9         connectionId: 6944db1a-f9f0-496f-91ba-4781e7f0490d
10         kind: warehouse-table
11         path:
12           - FUN
13           - BIKES
14           - TRIP
15       columns:
16         - id: Y3BEzKB09f
17           formula: '[TRIP/Id]'
18         - id: qQ09VyFetR
19           formula: '[TRIP/Duration]'
20       order:
21         - Y3BEzKB09f
22         - qQ09VyFetR
23   pages:
24     - id: jgZnqiZGOh
25       name: Page 1
26   layout: |
27     <?xml version="1.0" encoding="utf-8"?>
28     <Page type="grid" gridTemplateColumns="repeat(24, 1fr)" gridTemplateRows="auto" id="jgZnqiZGOh">
29       <Element elementId="z8NmRPjbEN" gridColumn="1 / 25" gridRow="1 / 21"/>
30     </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
> document:
>   schemaVersion: 1
>   kind: workbook
>   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
>   pages:
>     - id: jgZnqiZGOh
>       name: Page 1
>   layout: |
>     <?xml version="1.0" encoding="utf-8"?>
>     <Page type="grid" gridTemplateColumns="repeat(24, 1fr)" gridTemplateRows="auto" id="jgZnqiZGOh">
>       <Element elementId="z8NmRPjbEN" gridColumn="1 / 25" gridRow="1 / 21"/>
>     </Page>
> '

The endpoint updates the workbook with the new representation.