PythonWorkbooks

Workbooks in Nominal with Python

Workbooks are Nominal’s tool for creating and sharing interactive data visualizations and analyses. They can be created directly on the Nominal platform or programmatically using the Nominal Python SDK.

Creating a Workbook from a Template

Prerequisites

Make sure you have the nominal Python packages installed. You can install it using:

1pip3 install nominal

Connect to Nominal

When using the Nominal client library, there are two primary ways of authenticating:

First, run the following in your terminal and follow on-screen prompts to insert the base_url and API key:

$$ python -m nominal auth set-token
>
># Alternatively, use the globally installed CLI
>$ nom auth set-token

This will store your API key in a config file ~/.nominal.yml. The API key will automatically be used when using the client again.

1import nominal
2
3# Simply grab the "default" client using your stored credentials
4client = nominal.get_default_client()
5
6# Get details about the currently logged-in user to validate authentication
7# Will display an object like: `User(display_name='your_email@your_company.com', ...)`
8print(client.get_user())
1import nominal
2
3# Set login details for the user
4nominal.set_token("<insert api key>")
5
6# Get an instance of the client using provided credentials
7client = nominal.get_default_client()
8
9# Get details about the currently logged-in user to validate authentication
10# Will display an object like: `User(display_name='your_email@your_company.com', ...)`
11print(client.get_user())

NOTE: you should never share your Nominal API key with anyone. We therefore recommend that you not save it in your code and/or scripts.

  • If you trust the computer you are on, use nom to store the credential to disk.
  • Otherwise, use a password manager such as 1password or bitwarden to keep your token safe.
If you’re not sure whether your company has a Nominal tenant, please reach out to us.

Steps to Create a Workbook from a Template

  1. Obtain the Template RID:
    • Navigate to the Nominal platform.
    • Go to Workbooks ➔ Templates.
    • Click on the desired template.
    • In the top-left corner next to the template name, click the dropdown arrow ⌄.
    • Select Copy RID to copy the template RID to your clipboard.
  2. Obtain the Run RID:
    • Navigate to Runs.
    • Click on the run you want to associate with the workbook.
    • On the right side of the screen, locate the RID under “Metadata”.
  3. Create the Workbook Using the SDK:
1import nominal as nm
2
3nm.create_workbook_from_template(
4    template_rid = 'your_template_rid',
5    run_rid = 'your_run_rid',
6    title = 'My new workbook',
7    description = 'This is a new workbook created from a template',
8)

Accessing Your New Workbook

After creating the workbook programmatically:

  • Navigate back to Workbooks on the Nominal platform.
  • Locate your new workbook titled “My New Workbook”.
  • Open it to view and interact with your data visualizations.