Build from codeManage reports as code (Beta)

Get the code representation of a report (Beta)

View as Markdown

This documentation describes one or more public 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.

You can retrieve a code representation of an existing report by calling the Get a report endpoint with the reportId for the report and the query parameter includeContents=true.

This document provides step-by-step instructions for using this endpoint to retrieve the representation of an existing report. For more information on working with reports programmatically, see Manage reports as code.

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

User requirements

The ability to retrieve a report code representation requires the following:

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 report and retrieve the report ID

To retrieve the code representation of an existing report, you must know the unique reportId for that report. After you identify the report you want to retrieve the representation for, you can call the List reports endpoint to retrieve the reportId:

  1. Go to the Sigma Home page.

  2. In the navigation menu, select Documents.

  3. Click the Document type filter and select Reports.

    The list of your reports appears.

  4. Identify the report you want to retrieve the representation for by name, owner, or other details.

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

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

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

    {
      "entries": [
        {
          "reportId": "<reportId>",
          "reportUrlId": "<reportUrlId>",
          "createdBy": "<userId>",
          "updatedBy": "<userId>",
          "createdAt": "<timestamp>",
          "updatedAt": "<timestamp>",
          "name": "<reportName>",
          "url": "<reportUrl>",
          "path": "<folderPath>",
          "latestVersion": "<versionNumber>",
          "ownerId": "<userId>",
          "description": "<reportDescription>"
        },
        {
          "reportId": "<reportId>",
          "reportUrlId": "<reportUrlId>",
          "createdBy": "<userId>",
          "updatedBy": "<userId>",
          "createdAt": "<timestamp>",
          "updatedAt": "<timestamp>",
          "name": "<reportName>",
          "tags": [
            {
              "versionTagId": "<versionTagId>",
              "tagName": "<tagName>",
              "sourceVersion": "<versionNumber>",
              "taggedReportId": "<reportId>",
              "taggedAt": "<timestamp>"
            }
          ],
          "url": "<reportUrl>",
          "path": "<folderPath>",
          "latestVersion": "<versionNumber>",
          "ownerId": "<userId>"
        }
      ],
      "hasMore": <boolean>,
      "total": <number>,
      "nextPage": null
    }

  6. Identify the report you want to retrieve the representation for, and copy the reportId to pass to the Get a report endpoint.

Retrieve the representation

Using the reportId, make a GET request to the Get a report endpoint with the query parameter includeContents=true, using the following format:

curl --request GET \
    --url '<base_url>/v2/reports/<reportId>?includeContents=true' \
    --header 'Authorization: Bearer <access_token>' \
    --header 'accept: application/json'

The response body contains the report metadata, the documentVersion the representation was read from, and the code representation of the report in the contents field.

To receive the response as YAML instead of JSON, add the query parameter format=yaml or the header Accept: application/yaml:

curl --request GET \
    --url '<base_url>/v2/reports/<reportId>?includeContents=true&format=yaml' \
    --header 'Authorization: Bearer <access_token>'

To retrieve an earlier version of the representation, add the documentVersion query parameter. Without it, the endpoint returns the most recently published version. A documentVersion that does not exist returns a 404 error.

To see examples of report representations along with the instructions used to create them in the Sigma UI, see the Report representation example library.