This QuickStart is designed to support Sigma's API Code Samples and will demonstrate some common operations that customers may use the REST API for.

The actual code shown is available in Sigma's quickstart-public git repository

All code samples provided here are based on javaScript.

Target Audience

Developers who are evaluating or working with Sigma's REST API.

Prerequisites

Sigma Free Trial

Create Sigma Project Folder

Create a new folder on your local computer called Sigma_QuickStart_Public_Repo. It does not matter where, as long as you can navigate to it easily.

Source Code Editor - VSCode

For this QuickStart, we will demonstrate using Visual Studio Code (VSCode), but you may use any IDE you prefer.

VSCode, is a source-code editor developed by Microsoft for Windows, Linux and macOS. Features include support for debugging, syntax highlighting, intelligent code completion, snippets, code refactoring, and embedded Git.

Install VSCode from Microsoft's download site.

Run the installation with all defaults.

Open VSCode and make sure it loads without error and open the folder Sigma_QuickStart_Public_Repo we created earlier:

Runtime Environment - Node.js

While developers can use any language to communicate with the Sigma REST API, we will use the popular framework Node.js. for our examples.

Node.js (Node) is an open-source, cross-platform, back-end JavaScript runtime environment that runs on a JavaScript engine and executes JavaScript plaintext outside a web browser, which was designed to build scalable network applications.

Download and install Node.js from here:

Use the LTS (long term supported) version appropriate for your operating system.

Run the installer selecting all the defaults. We do not need to specify our project folder for this installation.

This will install both Node and the Node package manager (which manages optional Node components, which add more functionality).

The package manager is abbreviated to npm when running commands.

You can verify your installation using VSCode's built-in Terminal:

Run the command:

node -v

This should return the version number as below:

You can leave the Terminal session open for now.

Project Files

To save you time, we've stored all the necessary project files in Git. Simply download them using git clone and explore the recipes that interest you.

To clone the Git repository in VSCode, open the Command palette:

Type Clo into the command palette bar and then click Git: Clone:

Paste this URL and hit enter:

https://github.com/sigmacomputing/quickstarts-public.git

VSCode will prompt for the location to store the files on your computer. Navigate to the Sigma_QuickStart_Public_Repo folder and click the Select as Repository Destination button.

If prompted to open the cloned repository, click Open.

The repository contains other code samples you can explore, but we are interested in the sigma-api-recipes folder:

Once the project is open, return (or reopen a new) terminal session inside the project.

Run the command:

npm install

This will automatically install the project dependencies we use in the recipes.

You can verify that the dependencies (at the time of this QuickStart) were installed by running:

npm list

Environment Variables

We need to update the file that stores our environment variables.

First, you will need to provide the values for ClientID, Secret, Base and AuthURL.

This file keeps our keys out of our scripts and also contains other variables we may want to change in different use-cases:

Replace the placeholders for YourClientID and YourAPISecret. The values for auth and baseURL are for Sigma instances hosted in AWS-US. You may need to change these based on where your instance is running.

Save the file.

Footer

This section demonstrates the code that was provided on the API Code Samples > Authentication: Get Access Token page, located here.

Description

This script retrieves a bearer token from the Sigma API using client credentials authentication. It extracts required credentials from environment variables, sends a POST request to the authentication endpoint, and logs the obtained token. The function getBearerToken can be imported into other scripts for accessing protected resources.

This actual javascript is available as part of the git repository mentioned earlier or is available to copy directly from our API Code Samples site under: Authentication: Get Access Token and returns a bearer token (token). It also exports a Javascript function to request a bearer token (token) each time it is called.

` In the project root directory, open the file `get-access-token.js` and review it's contents. Each section is commented so it can be understood.

Start the VSCode debugger against this code by pressing F5 on your keyboard.

If prompted by VSCode to select a debugger, select Node.js.

The VSCode debugger console will show this API response if the .env variables are configured correctly:

The script is configured to run standalone, as well as export a function that we can call from other scripts too.

This is why we show the bearer token twice in the response. Other scripts that call this one, will only show the token one time in the console.

The ability to run it standalone is only for convenience, so that we can verify it obtains a token.

We can now move on to use cases, leveraging the getBearerToken function:

Footer

Description

We will start with a very simple example that calls the Members > Get endpoint, found here.

This section demonstrates the code that was provided on the API Code Samples > Member> list-all page, located here.

This script retrieves all members from the Sigma API by making GET requests with pagination until all members are fetched. It first obtains a bearer token for authentication, then iterates through each page of member data, concatenating the results into an array. Finally, it logs the fetched members to the console in a readable JSON format. Errors during the process are logged with detailed error messages

Running the Script

Open the file list-all.js in the members folder:

Each code block is commented to explain what operations are being performed.

Press F5 to run the script with VSCode's debugger.

The expected response is:

Footer

This section demonstrates the code that was provided on the API Code Samples > Member: Update page, located here.

Description

This script updates the account type of a member on the Sigma platform by sending a PATCH request to the API with the new member type. It retrieves the necessary information such as the member ID and new member type from environment variables and constructs the request URL accordingly. Finally, it makes the API call to update the member's account type.

Create Test Member

Let's create new member in Sigma to test with.

If you prefer, you can use any non-production user you want, but we recommend creating a test user for this purpose.

If you are not sure how to create a user (member) in Sigma, please refer to this documentation..

We created a test user using Gmail's email alias feature.

Our test user is called sales_rep.

Make a note of the test user's memberId. Again, we could get this using the API, but in this example, we will just copy it from the URL, when looking at the user's profile from the Administration > People list:

In this case, the memberId is KteJXJQfHuei5GxxY9hQOnFZHP91A. Yours will be different.

Add these values to the .env file we created and save the change.

MEMBER_ID=KteJXJQfHuei5GxxY9hQOnFZHP91A
NEW_MEMBER_TYPE=Creator

Change Test Members' Account Type

Our test user is currently a Viewer account type. We want to call the Sigma API endpoint to Update the specified member account type to Creator.

We will be using the Update the specified member endpoint.

Running the Script

Open the file update.js in the members folder.

Each code block is commented to explain what operations are being performed.

Press F5 to run the script with VSCode's debugger.

The expected response is:

A quick check against the member in Sigma shows them having the Creator account type now:

Footer

This section demonstrates the code that was provided on the API Code Samples > Members: Change Email Address page, located here.

Description

This script automates the process of changing a member's email address in the Sigma. Here's a summary of what the code does:

Running the Script

Open the file change-email.js in the members folder:

Each code block is commented to explain what operations are being performed.

Select a test user from Sigma and place their email address in the .env file, commented out. Replace the active email address in .envwith a variation.

For example:

Press F5 to run the script with VSCode's debugger.

The expected response is:

Confirm the new email has been set in Sigma:

You can revert the email by editing the .env file and rerunning the script's debugger.

Footer

This section demonstrates the code that was provided on the API Code Samples > Member: Recent Workbook page, located here.

Description

This script fetches recent documents and folders for a specified member from the Sigma API. It retrieves a bearer token for authentication, constructs the API endpoint URL, and makes a GET request to fetch the recent items. The response is then processed to extract relevant information and sorted by the last interaction date in descending order before logging the results. In this use case, we want to return a list of the Workbooks (by name), the permission and when they last accessed for each Workbook, ordered by most recent first.

Running the Script

Open the file called .env and ensure that the memberID is set for someone who has accessed Workbooks in your Sigma instance. In a trial environment, pick someone who is very active or yourself if that is the case. As long as there is activity, it does not matter otherwise.

If you are not sure how to obtain a memberID, review the section called Create Test Member in the step called Member: Update.

Open the file called recent-workbooks.js in the members folder.

Each code block is commented to explain what operations are being performed.

Press F5 to run the script with VSCode's debugger.

The expected response is:

Footer

This section demonstrates the common steps to add a new member (user) to Sigma, via the API.

Description

This script creates a new member in Sigma by sending a POST request to the API endpoint. It dynamically generates a unique email address for the new member to ensure uniqueness during testing.

The script utilizes environment variables to specify the base URL, email, first name, last name, and member type.

Upon successful creation, it logs the newly added member's details, and in case of an error, it logs the error message.

We will break each step into it's own script and once each step is verified to work, we will run them as one step.

The steps are: 1: Create a unique, new member 2: Create a new Workspace for the member 3: Grant permission to the workspace to the new member 4: Add the member to a team 5: Grant permission to a connection (data) to the member

In each section, we export the script to a Javascript function so that when we are done, we can put it all together to run as one script.

Required Body Parameters

Open the .env file and add the required parameters. You will need to provide different values as shown below:

EMAIL={your example email}
NEW_MEMBER_FIRST_NAME=API
NEW_MEMBER_LAST_NAME=Generated
NEW_MEMBER_TYPE=Viewer

WORKSPACEID=
TEAMID=
CONNECTIONID=

Save the changes.

Running the "create-new.js" script

Open the file create-new.js in the members folder:

Each code block is commented to explain what operations are being performed.

Note the line of code that uses the Javascript split function to ensure that the members's email address is unique:

const newMemberEmail = `${baseEmail.split('@')[0]}+${new Date().getTime()}@${baseEmail.split('@')[1]}`;

Press F5 to run the script with VSCode's debugger.

The expected response is:

Copy the memberId provided in the response. We will use that in the next step.

Checking in the UI, we can see the new member has been added. This member does not have a Workspace, the rights to one, or rights to any data (Connections). We will do each of these in steps first. Then will will put it all together in a script we will call `Member: Onboarding"

Running the "create-workspace.js" script

Update .env with the memmberId we received in the create-new script response:

Open the file create-workspace.js in the members folder.

Each code block is commented to explain what operations are being performed.

Press F5 to run the script with VSCode's debugger.

The expected response is:

Copy the WorkspaceId in the response. We will use that in the next step.

Checking in the Sigma UI we can see the new Workspace:

Running the "create-workspace-permission.js" script

Open the file .env and update the value for WORKSPACEID that we received from the create-workspace.js script

Save the change.

Open the file create-workspace-permission.js in the members folder.

Each code block is commented to explain what operations are being performed.

Press F5 to run the script with VSCode's debugger.

The expected response is:

URL sent to Sigma: https://aws-api.sigmacomputing.com/v2/workspaces/678ba3ea-00c8-4702-871e-6418279e9796/grants
New workspace permission added successfully: {}

Checking in the Sigma UI we can check the Workspace sharing permissions:

Running the "add-member-to-team" script

For this script we will need to have a TeamId is Sigma that we want to assign the new member to.

We already have a script we built in section 5, and we can use that to update the member's team assignment. We can grab the TeamId for one from the UI for this demonstration:

Open the file .env and update the value for TEAMID, using your value.

Save the change.

Open the file add-member-to-team.js in the members folder.

Each code block is commented to explain what operations are being performed.

Press F5 to run the script with VSCode's debugger.

The expected response is:

URL sent to Sigma: https://aws-api.sigmacomputing.com/v2/teams/25d48b2e-b36b-4db2-98a9-2c474f4144da/members
Member successfully added to team: {}

Checking in the Sigma UI we can check the Workspace sharing permissions:

Running the "create-connection-permission.js" script

For this script we will need to have a Connection is Sigma that we want to grant the new member permission to use.

There is an endpoint to GET all connections, but we can also just grab the connectionId for one from the UI for this demonstration:

The connection shown above has no grants yet and the connectionId is in the URL (#2 in the image).

Open the file .env and update the value for CONNECTIONID, using your value.

Save the change.

Open the file create-connection-permission.js in the members folder.

Each code block is commented to explain what operations are being performed.

Press F5 to run the script with VSCode's debugger.

The expected response is:

URL sent to Sigma: https://aws-api.sigmacomputing.com/v2/workspaces/678ba3ea-00c8-4702-871e-6418279e9796/grants
New workspace permission added successfully: {}

Checking in the Sigma UI (from Home > Connections) we see our new member has connection permission:

Putting it all together

Now that each step is working as expected, we can create a master script that calls each step's module and just one run script to onboard a new member.

We are faced with a challenge in that we do not know the memberId until the first script is run. Previously, we hard-coded this value and for the sake of not changing any of the other scripts, we will manually run the create-new.js script and then run all the other scripts from one master script.

This method strikes a balance between demonstrating individual script functions and showing how they can be integrated into a larger workflow with a simple manual step bridging the gap.

Open the file create-new.js in the members folder:

Press F5 to run the script with VSCode's debugger.

Copy the memberId provided in the response, and update the MEMBERID with this new value.

Next, open the file master-script.js and press F5 to run the script with VSCode's debugger.

Each code block is commented to explain what operations are being performed.

Press F5 to run the script with VSCode's debugger.

The expected response is:

URL sent to Sigma: https://aws-api.sigmacomputing.com/v2/workspaces/678ba3ea-00c8-4702-871e-6418279e9796/grants
New workspace permission added successfully: {}
Connection permissions granted successfully.
Onboarding process completed successfully.

Verify the new member is created in the UI, has workspace permission, is a member of the expected team, and has connection permission.

Footer

This section demonstrates the code that was provided on the API Code Samples > Workbook: Pagination page, located here.

Description

This script fetches all workbooks from the Sigma API, handling pagination for large datasets.

It retrieves a bearer token for authentication, constructs the API endpoint URL with pagination parameters, and iteratively fetches workbooks (in groups of 50) until all pages are retrieved.

The fetched workbook data is then formatted into a table for display in the console.

If an error occurs during the process, it is logged accordingly.

Query parameters page and limit are commonly used together in APIs to implement pagination. This mechanism allows clients to request data in discrete chunks or "pages", making it easier to handle large datasets. Here's how these parameters typically work together in API use cases:

Many of Sigma's API operations support page and limit as query parameters.

These parameters can be used in different ways but generally they are used to:

1: Reduces the load on the server and the amount of data transmitted over the network at any one time. 2: Make it easier for clients to consume data in manageable chunks, especially important for user interfaces where users scroll through lists or tables of data. 3: Provide flexibility so customers can adjust the limit based on their current needs or capabilities/ For example, requesting more data on a powerful desktop browser or less on a mobile device with limited bandwidth.

Running the Script

Open the file pagination.js in the workbooks folder:

Each code block is commented to explain what operations are being performed.

Press F5 to run the script with VSCode's debugger.

The expected response is:

Footer

This section demonstrates the code that was provided on the API Code Samples > Workbook: List All page, located here.

Description

This script fetches all workbooks accessible to a specific member based on their memberId. It retrieves the member's files, filters out the workbooks, and then lists their names, URLs, and version numbers.

Running the Script

Open the file list-all.js in the workbooks folder:

Each code block is commented to explain what operations are being performed.

Press F5 to run the script with VSCode's debugger.

The expected response is:

Footer

A common use case is to provide the user a list of workbooks that are shared with, and have the list hyperlinked to the workbook so the user can just click and go.

This section demonstrates the code that was provided on the API Code Samples > Workbook: Shared with Me page, located here.

Description

This script fetches all workbooks accessible to a specific member based on their memberId. It retrieves the member's files, filters out the workbooks, and then lists their names, URLs, and version numbers.

Running the Script

Open the file shared-with-memberId.js in the workbooks folder:

Each code block is commented to explain what operations are being performed.

Press F5 to run the script with VSCode's debugger.

The expected response is:

Footer

A common use case is to programmatically initiate an existing materialization job in Sigma, via API.

This section demonstrates the code that was provided on the API Code Samples > Workbook: Workbook: Initiate Materialization Job page, located here.

Description

This script initiates a materialization job for a specified workbook.

It retrieves required the sheet ID, from the materialization schedules of the workbook. Then, it starts the materialization job using the workbookId and sheet ID.

After initiating the job, it continually checks the status of the materialization until it either completes successfully or fails. Once the status indicates that the materialization is "ready", the script stops execution, indicating that the job has been completed successfully.

Then, it starts the materialization job using the workbookId and sheet ID. After initiating the job, it continually checks the status of the materialization until it either completes successfully or fails.

Once the status indicates that the materialization is "ready", the script stops execution, indicating that the job has been completed successfully.

Create a Materialization Schedule

Log into Sigma as an Administrator.

Navigate to a Workbook that you want to materialize. We created a simple workbook that has two pages, one for a Dashboard and one for the source data, which is based on the Sigma Sample Database > Retail > Plugs Electronics > Plugs Electronics Hands On Lab table. This second page is labeled Data.

On the Data page, we select Schedule materialization as shown:

We configured the schedule to run once a month:

The materialization job ("Job") needs to run to success the first time, and then is available to the API.

We can check the status of all Jobs by navigating to Administration > Materializations:

We can now call this Job using the API.

Running the Script

Open the file initiate-materialization.js in the workbooks folder:

Each code block is commented to explain what operations are being performed.

Press F5 to run the script with VSCode's debugger.

As the script runs the materialization status is checked and goes through three states, pending, building and ready.

Pending indicates job is queued.

Building indicates the job is running.

Ready indicated the job is completed to success.

The expected response looks like this:

If we want to check the status of this Job, we can use the UI, by navigating to Administration > Materializations.

Footer

This section demonstrates the code that was provided on the API Code Samples > Workbook: List all Input Tables page, located here.

Description

This script performs a targeted search across all workbooks for an organization, looking specifically for elements of the type "input-table."

It logs concise details about each found element, including the workbook's name and path, the page's name, and the input table's name and ID.

It's designed to run silently, only outputting information when relevant elements are discovered, and includes basic error handling to manage issues quietly without interrupting the process.

Running the Script

Open the file all-input-tables.js in the workbooks folder:

Each code block is commented to explain what operations are being performed.

Press F5 to run the script with VSCode's debugger.

The expected response is:

Footer

This section demonstrates the code that was provided on the API Code Samples > Workbook: Export to CSV with Date Range Parameters page, located here.

Description

This script facilitates the automation of exporting data from Sigma. Here's a breakdown of its functionality and its potential utility for Sigma customers:

This script can be particularly useful for Sigma customers who need to automate the extraction of data from Sigma for further analysis, reporting, or integration with other systems. By automating the export process, customers can save time and ensure consistency in data retrieval tasks.

Running the Script

Open the file export-workbook-element-csvs.js in the workbooks folder:

Each code block is commented to explain what operations are being performed.

In our sample code, the date range is set in this code block:

The "DateFilter" in code refers to the Control ID that is filtering the data in our Sigma workbook:

Press F5 to run the script with VSCode's debugger.

The expected response is:

The contents of export.csv is:

Footer

This section demonstrates the code that was provided on the API Code Samples > Workbook: Export to CSV with Date Range Parameters page, located here.

Description

This script automates the process of exporting a Sigma workbook to PDF format and downloading the export once it's ready.

It loads environment variables from an .env file for configuration, including the base URL for the Sigma API and the workbook ID.

The script then triggers an export job for the entire workbook in PDF format, specifying the layout as portrait.

It continuously checks the export's readiness for download and, once ready, downloads the exported PDF file.

This automation simplifies the process of exporting Sigma workbooks to PDF, enabling users to streamline their workflow and access PDF exports efficiently."

Running the Script

Open the file export-workbook-pdf.js in the workbooks folder:

Each code block is commented to explain what operations are being performed.

Set a value for WORKBOOK_ID in .env that will produce results that might present well in PDF format.

We used the Plugs Sale Performance Workbook template to save a workbook for this testing.

Press F5 to run the script with VSCode's debugger.

The expected response is:

The exported PDF is saved here: export-workbook-pdf.pwd:

The PDF looks like this export-workbook-pdf.pwd:

Footer

This section demonstrates the code that was provided on the API Code Samples > Workbook: Copy Workbook to Member "My Documents" Folder page, located here.

Description

This script automates the process of copying a specific workbook for a designated user in Sigma. Here's a breakdown of what the script does:

Running the Script

Open the file copy-workbook-folder.js in the workbooks folder:

Each code block is commented to explain what operations are being performed.

Set a value for WORKBOOK_ID and MEMBERID in .env to reflect which member will receive a copy of your workbook.

It does not matter which workbook you want to use for this testing, as long as it is published.

We need to select a member to use as the "recipient" of this copied workbook. In our case, we selected our QA user.

By impersonating our user, we can see that they only have two folders in My Documents at the moment.

We are expecting this API script to place a copy of the workbook in this location, and we use impersonation to verify that.

Press F5 to run the script with VSCode's debugger.

The expected response is:

In Sigma, we can see the copied workbook has been created in their My Documents folder:

Footer

This section demonstrates the code that was provided on the API Code Samples > Workbook: Copy Workbook to Member "My Documents" Folder page, located here.

Description

This script fetches a list of workbooks available to a specific member from the API, retrieves the workbook name, and constructs embed URLs for each workbook.

Here's a summary of its functionality:

The script can be executed directly, and the main function is exported for use in other modules if needed.

Running the Script

Open the file generate_workbook_embed_path.js in the embedding folder:

Each code block is commented to explain what operations are being performed.

Set a value for MEMBERID in .env to reflect which member's workbooks to generate embed urls for.

It does not matter which member you want to use for this testing, as long as they have some workbooks they created or have been shared with.

Press F5 to run the script with VSCode's debugger.

The expected response is:

Footer

This section demonstrates the code that was provided on the API Code Samples > Teams: Bulk Assign Members page, located here.

Description

This script is designed to bulk assign existing members to a specific team within Sigma Computing's platform, utilizing the members' emails as identifiers. It operates by reading a list of email addresses from a .member-emails file, finding each member's ID through the Sigma API, and then assigning each member to a designated team.

Here's a summary of how the script works (not including the environmental setup, which has been covered earlier):

1: Reading Member Emails: Reads a list of member emails from a .member-emails file located relative to the script. This file contains the emails of the members to be assigned to the team, separated by commas.

2: Member ID Lookup: For each email, makes an API request to Sigma's /members endpoint to find the member's ID based on their email. This is necessary because the subsequent API call to assign a member to a team requires the member's ID.

3:Assigning Members to Team: Once the member ID is obtained, makes another API request to the /teams/{teamId}/members endpoint to add the member to the specified team using the team ID provided in the environment variables.

4: Error Handling: Includes error handling for various steps of the process, logging any issues encountered during the member lookup or assignment process.

5: Script Execution: Orchestrates the overall process through a main function that initiates the token retrieval, member processing, and assignment tasks.

Running the Script

Open the file bulk-assign-team.js in the tables folder:

Each code block is commented to explain what operations are being performed.

In this example, we had three emails in the ../member-emails file that the script will iterate through and add to a team.

Configure the emails in the file using comma separation.

The teamId is specified in the .env file.

Press F5 to run the script with VSCode's debugger.

The expected response is (showing two members being added in the screenshot):

Footer

In this QuickStart we covered setting up a local test environment leveraging Sigma's git repository of sample API recipes in support of a variety of use cases.

Additional Resource Links

Blog
Community
Help Center
QuickStarts

Be sure to check out all the latest developments at Sigma's First Friday Feature page!

   

Footer