Build from codeManage workbooks as code (Beta)

Create a workbook from a code representation (Beta)

View as Markdown

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 create a workbook from a code representation by calling the Create 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 create a workbook from a code representation. For more information on working with workbooks programmatically, see Manage workbooks as code.

User requirements

The ability to create 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.

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.

Prepare a code representation

To create a workbook using the Create a workbook from a code representation endpoint, you must first construct a valid code representation of a workbook.

To see example representations with various features and configurations, see the Example library.

You can prepare a representation using any of the following options:

Prepare the representation manually

You can prepare the code representation of a workbook manually by constructing JSON or YAML with the required fields.

A valid representation of a workbook has the following fields:

  • name: The name of the workbook.
  • folderId: The ID of the folder to create the workbook in. Required for this endpoint.
  • document: An object describing the contents of the workbook.
    • schemaVersion: The version of the representation schema to use.
    • kind: The type of document the representation describes. For a workbook, the value is workbook.
    • elements: An array of every element in the workbook, across all pages. Can be empty.
    • pages: An array of page objects.
      • id: An ID for the page.
      • name: The name of the page.
    • layout: An XML string that assigns each element to a page and positions it.

Every element in document.elements must be placed in the layout, because the layout is what assigns an element to a page. For more information, see Customize the layout of a workbook in code representation.

Because a valid code representation of a workbook can contain many nested objects with references to one another, Sigma does not recommend preparing large representations manually. See Prepare the representation based on an existing workbook or Prepare the representation using an AI assistant for alternative options to prepare a representation.

As an example, the following POST request creates an empty workbook in a specified folder:

$curl --request POST \
>    --url <base_url>/v2/workbooks/spec \
>    --header "Authorization: Bearer <access_token>" \
>    --header 'content-type:application/json' \
>    --data '{"name":"Sample Workbook","folderId":<folderId>,"document":{"schemaVersion":1,"kind":"workbook","elements":[],"pages":[{"id":<pageId>,"name":"Page 1"}],"layout":"<?xml version=\"1.0\" encoding=\"utf-8\"?>\n<Page type=\"grid\" gridTemplateColumns=\"repeat(24, 1fr)\" gridTemplateRows=\"auto\" id=\"<pageId>\"/>\n"}}'

The representation for the workbook created by that request appears as follows:

1{
2    "workbookId": <workbookId>,
3    "name": "Sample Workbook",
4    "url": <workbookUrl>,
5    "documentVersion": 1,
6    "latestDocumentVersion": 1,
7    "ownerId": <userId>,
8    "folderId": <folderId>,
9    "createdBy": <userId>,
10    "updatedBy": <userId>,
11    "createdAt": <timestamp>,
12    "updatedAt": <timestamp>,
13    "document": {
14        "schemaVersion": 1,
15        "kind": "workbook",
16        "elements": [],
17        "pages": [
18            {
19                "id": <pageId>,
20                "name": "Page 1"
21            }
22        ],
23        "layout": "<?xml version=\"1.0\" encoding=\"utf-8\"?>\n<Page type=\"grid\" gridTemplateColumns=\"repeat(24, 1fr)\" gridTemplateRows=\"auto\" id=\"<pageId>\"/>\n"
24    }
25}

The folderId and document.layout fields are both required. A POST request without a top-level folderId is rejected, as is one without a layout. For more information on using the layout field to customize a workbook, see Customize the layout of a workbook in code representation.

You can add elements like tables, charts, and more to the representation by including them in the document.elements array and placing each one in the layout. To learn about the configuration of an element in the representation, see the entry for that element in the Workbook representation example library.

Prepare a representation from multiple YAML documents

When preparing a code representation of a workbook, you can define the workbook contents in multiple YAML documents, and combine them into one workbook when calling the Create a workbook from a code representation endpoint.

As an example, the following POST request creates an empty workbook in a specified folder with two pages, each defined in a separate YAML document:

$curl --request POST \
>        --url <base_url>/v2/workbooks/spec \
>        --header "Authorization: Bearer <access_token>" \
>        --header "content-type: application/yaml" \
>        --data 'name: Sample Workbook
>        folderId: <folderId>
>        document:
>          schemaVersion: 1
>          kind: workbook
>          elements: []
>          pages:
>            - id: <pageId1>
>              name: Page 1
>          layout: |
>            <?xml version="1.0" encoding="utf-8"?>
>            <Page type="grid" gridTemplateColumns="repeat(24, 1fr)" gridTemplateRows="auto" id="<pageId1>"/>
>            <Page type="grid" gridTemplateColumns="repeat(24, 1fr)" gridTemplateRows="auto" id="<pageId2>"/>
>        ---
>        document:
>          pages:
>            - id: <pageId2>
>              name: Page 2'

The JSON representation for the workbook created by that request appears as follows:

1{
2    "workbookId": <workbookId>,
3    "name": "Sample Workbook",
4    "url": <workbookUrl>,
5    "documentVersion": 1,
6    "latestDocumentVersion": 1,
7    "ownerId": <userId>,
8    "folderId": <folderId>,
9    "createdBy": <userId>,
10    "updatedBy": <userId>,
11    "createdAt": <timestamp>,
12    "updatedAt": <timestamp>,
13    "document": {
14        "schemaVersion": 1,
15        "kind": "workbook",
16        "elements": [],
17        "pages": [
18            {
19                "id": <pageId1>,
20                "name": "Page 1"
21            },
22            {
23                "id": <pageId2>,
24                "name": "Page 2"
25            }
26        ],
27        "layout": "<?xml version=\"1.0\" encoding=\"utf-8\"?>\n<Page type=\"grid\" gridTemplateColumns=\"repeat(24, 1fr)\" gridTemplateRows=\"auto\" id=\"page-1\"/>\n<Page type=\"grid\" gridTemplateColumns=\"repeat(24, 1fr)\" gridTemplateRows=\"auto\" id=\"page-2\"/>\n"
28    }
29}

When combining multiple YAML documents in one workbook code representation, each document contributes entries to the document.pages and document.elements arrays, and the API merges them into one workbook. You cannot combine contents from multiple documents inside one page.

No key can appear in more than one YAML document in the same request. Because document.layout is a single string covering every page, declare it in exactly one document, and list every page and element it references. A request that repeats a key is rejected with an error such as Invalid YAML: Duplicate key "document.layout" across YAML documents.

Prepare the representation based on an existing workbook

You can prepare a code representation of a workbook by retrieving the representation of an existing workbook and making changes based on that representation.

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.

To get the representation of an existing workbook, see Get the code representation of a workbook.

Prepare the representation using an AI assistant

You can prepare a code representation of a workbook using an AI assistant to compose the representation. Sigma recommends providing examples of representations to the agent to improve accuracy and performance, either by providing an LLM-friendly version of our documentation and example library or using an agent skill.

To learn more about using the Sigma documentation with AI assistants, see Add Sigma documentation as context to chat interactions. For examples of workbook code representations, see the Workbook representation example library.

To learn more about skills for AI assistants using Sigma, see Install skills for AI assistants. Users with access to the workbook code representation private beta can request a skill directly from Sigma.

Identify where to create the workbook

To create a workbook from a representation, you must identify the folder to create the workbook in. You can identify a folder and then call the List files endpoint to retrieve the id for the folder:

  1. Go to the Sigma Home page.

  2. In the navigation menu, select Documents.

  3. Click the Document type filter and select Folders.

    The list of your folders appears. If there is no folder for you to create the workbook in, select Create folder to create one.

  4. Identify the folder you want to retrieve the id for, by name, creator, or other details.

  5. Call the List files endpoint, with a query parameter to filter for folders:

    $curl --request GET \
    >    --url '<base_url>/v2/files?typeFilters=folder' \
    >    --header 'Authorization: Bearer <access_token>' \
    >    --header 'accept:application/json' \
    >    --header 'content-type: application/x-www-form-urlencoded'

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

    1{
    2    "entries": [
    3        {
    4            "id": "<folder_id>",
    5            "urlId": "<folder_url_id>",
    6            "name": "<folder_name>",
    7            "type": "folder",
    8            "parentId": "<parent_folder_id>",
    9            "parentUrlId": "<parent_folder_url_id>",
    10            "permission": "<permission_level>",
    11            "path": "<folder_path>",
    12            "badge": null,
    13            "ownerId": "<owner_user_id>",
    14            "createdBy": "<creator_user_id>",
    15            "updatedBy": "<updater_user_id>",
    16            "createdAt": "<creation_timestamp>",
    17            "updatedAt": "<update_timestamp>",
    18            "isArchived": false
    19        }
    20    ],
    21    "total": <total_number_of_folders>,
    22    "nextPage": null
    23}

  6. Using the name or other details you identified in step 4, find the folder you want to retrieve the id for, and copy the id from the response body.

  7. Add the folder id to the code representation you prepared earlier as the folderId.

Call the Create a workbook from a code representation endpoint

Using the access token and code representation you prepared in the previous steps, make a POST request to the Create a workbook from a code representation endpoint using the following format:

$curl --request POST \
>    --url <base_url>/v2/workbooks/spec \
>    --header 'Authorization: Bearer <access_token>' \
>    --header 'content-type:application/json' \
>    --data '<representation>'

The endpoint creates the workbook and returns the workbookId in the response body.