Dashboard Controls in the URL

IMPORTANT: This document is specific to Sigma dashboards. To learn about this topic for Sigma’s new Workbooks feature, please visit Workbook Controls in the URL.

In Sigma you can update the values of dashboard controls via URLs. This can be done on the Dashboard URL itself, or within the dashboard on external image links and embed links. 

If controls are hidden, you can only update them when through the application embedding process, not directly in the URL. 

As users interacts with a dashboard, Sigma automatically updates the URL. Each control value that is changed to something other than the default value will be reflected in the URL. This means that if someone shares a dashboard via URL, the recipient will see the same dashboard as the sender. 

For each type of control there are different formats to add into the URL.

For example in this Dashboard when there are no edits added, the URL would look like https://app.sigmacomputing.com/example-org/db/Cohort-Analysis-Dashboard-6EG4OdhAsugsGqUWfDVrMm

Screen_Shot_2020-10-28_at_11.27.42_AM.png

 

Let's add a filter value to the Product Type control.

Screen_Shot_2020-10-28_at_11.27.29_AM.png

The URL would be updated to https://app.sigmacomputing.com/example/db/Cohort-Analysis-Dashboard-6EG4OdhAsugsGqUWfDVrMm?Product%20Type=Music

Notice ?Product%20Type=Music was appended to the end of the URL as a Search Param. The addition to the URL shows that the control User Revenue has the min value of 4000 and no max value. Sigma automatically updates these values so that if the Viewer wants to send over a copy of the dashboard with their custom control values, they can just copy the URL.

Generating a URL

There are times when you may want to generate a URL directly rather than copying from the address bar. To do that, follow the steps below. 

  1. Open settings for the control you want to update through the URL. Note the Control ID and the Control Type.
    The Control ID will be used to identify which control you want to update the value of. The Control type will help determine what format the value needs to be in.

  2. Format the value
    In this step, we'll format the controls and values to be URL encoded. Certain characters can't be present in URLs, so we'll replace them with codes as needed. If your Control ID or control values include spaces, commas, question marks or other characters like that, it will need to be encoded. 

Control Type

 

Type

 

Format

 

Example

 

Comment

 

Textbox

  • String

  • Number

encodeURIComponent(<control_id>)=encodeURIComponent(<control_value>)

  • Customer%20Id=merchant%201

<control_id> is Customer Id

<control_value> is merchant 1

Date Picker

  • Datetime

encodeURIComponent(<control_id>)=<control_value>

  • start_date=2014-05-01

  • start_time=2014-05-01T02:00

<control_value> is the ISO Date (without Z)

Example 1

  • <control_id> is start_date

  • <control_value> is 2014-05-01

Example 2

  • <control_id> is start_time

  • <control_value> is 2014-05-01T02:00

Date Range

  • Datetime

encodeURIComponent(<control_id>)=min:<min_date>,max:<max_date>

  • Analysis%20Time%20Frame=min:2020-04-01,max:next-day-7

  • Analysis%20Time%20Frame=min:2020-04-01,max:

  • Analysis%20Time%20Frame=min:prior-year-0,max:2020-04-01T02:00

 

Where <min_date>/<max_date> is an exact date (ISO Date) or a relative date (<date_type>_<date_unit>_<date_number>

Example 1

  • <control_id> is Analysis Time Frame

  • <min_date> is 2020-04-01

  • <max_date> is next-day-7 which means the end date is 7 days in the future

Example 2

  • <min_date> is 2020-04-01

  • <max_date> is null which means there is no end date. (So this time frame is any day after 2020-04-01)

Example 3

  • <min_date> is prior-year-0 which means the start of the current year.

  • <max_date> is 2020-04-01T02:00

Value List

  • String

  • Number

encodeURIComponent(<control_id>)=encodeURIComponent(<control_value1>)[,encodeURIComponent(<control_value2>)…]

  • Employee%20Name=Jason%20Frantz

  • Employee%20Name=Jason%20Frantz,Rob%20Woollen,James%20Gale

Values is a list of comma separated URL encoded values. There can be as many values as you want.

Example 1

  • <control_id> is Employee Name

  • <control_value1> is Jason Frantz

Example 2

  • <control_value1> is Jason Frantz

  • <control_value2> is Rob Woollen

  • <control_value3> is James Gale

Value List

  • Datetime

encodeURIComponent(<control_id>)=<control_value1>[,<control_value2>…]

  • birthday=1970-05-01,1991-01-24

  • birthday=1991-01-24

Values are comma separated ISO Date (No URL encoding for values)

Number Range

  • Number

encodeURIComponent(<control_id>)=min:<min_value>,max:<max_value>

  • User%20Revenue=min:4000.5,max:

  • User%20Revenue=min:4000.5,max:5000

Example 1 means any value greater than 4000.5

Example 2 means any value between 4000.5 to 5000

Checkbox/Switch

  • Boolean

encodeURIComponent(<control_id>)=true,false

  • is_weekend=true,false

  • is_weekend=true

  • is_weekend=false

 

 

Simple Textbox Example

This is the most basic control in Sigma. Where the control is just a single value. Let’s update the control below to have the value merchant 1.

mceclip0.png

Looking from the Control Format above. We know that the URL encoding is. 

encodeURIComponent(<control_id>)=encodeURIComponent(<control_value>)

control_id is the id found in Step 1. While control_value is the value you want.

After encoding it into the URL, it should look like this

 Customer%20Id=merchant%201

Because the Id and the value had spaces in between we had to encode it to be URL safe which is where the %20 comes from.

Date Range Details

Format is in

encodeURIComponent(<control_id>)=min:<min_date>,max:<max_date>

Where min_date / max_date is an exact date (ISO Date) or relative date (in the format <date_type>_<date_unit>_<date_number>)

  • date_type is prior for the past or next for future

  • date_unit can be minute, hour, day, week, month, quarter, or year

  • date_number is a numeric value

Analysis%20Time%20Frame=min:2020-04-01,max:next-day-7 

means that the min date on 2020-04-01 to 7 days in the future. Note if the <min_date> or <max_date> is empty it means there isn’t a date set.

Analysis%20Time%20Frame=min:2020-04-01,max:

 would mean any time after 2020-04-01.

Note: Any relative format for min_date would always be the start of.. i.e prior-year-1 means the start of the previous year or next-year-0 would mean the start of the current year.

Any relative format for max_date would always be the end of… i.e next-year-1 would mean the end of the next year. or next-year-0 would mean the end of the current year.

 

IMPORTANT: This document is specific to Sigma dashboards. To learn about this topic for Sigma’s new Workbooks feature, please visit Workbook Controls in the URL.