Apply control values with URL parameters

You can use URL parameters to update control values in native and embedded workbooks. 

This document explains how to append URLs with query parameters and use URI encoding to format URLs for specific control types.

Append a URL with a control value

When a workbook URL doesn't include parameters, Sigma applies the control values selected in the workbook's published version.

A URL without parameters displays as follows:

https://app.sigmacomputing.com/embed/{workbookID}

or

https://app.sigmacomputing.com/{org}/{workbookID}

To apply the value "2016" to the Year control, append a question mark (?) and the key-value pair Year=2016 as a URL parameter.

The updated URL displays as follows:

https://app.sigmacomputing.com/embed/{workbookID}?Year=2016

Since the control targets all three data elements on the page, each element updates to show data from the year 2016 only.

Append multiple parameters and control values

To include multiple URL parameters, separate each key-value pair with an ampersand (&). To apply multiple values to the same control, separate the values with a comma (,).

A URL with multiple parameters and control values displays as follows:

https://app.sigmacomputing.com/embed/{workbookID}?Year=2016&Region=West,Southwest

Directly generate a URL

There are times when you may want to generate a URL directly rather than copying from the address bar. To do so, use the following steps:

Open settings for the control you want to update through the URL

Note the control ID and the control type. The control ID identifies which control you want to update. The control type determines what format is required for the value.

Format the value

Format the controls and values to be URL-encoded. Some characters cannot be used as-is in a URL.
If your control ID or control values contain special characters, you must use the URL-encoded form instead. For example, the code for space is %20. See the list of all Special characters for URL parameters.

Notes

You can use ":null" as a special value that denotes the null primitive value.

You can use ":empty" as a special value that denotes the empty string "".

Date values are parsed by default with your Sigma organization's Account Time Zone. You can override this behavior to use the UTC +0 time zone. To do so, append a "Z" at the end of the timestamp (representing the Zulu Time Zone). For example: 2023-06-08T00:00:00Z.

Textbox Formats

TypesText, Number
FormatencodeURIComponent(<control_id>)=encodeURIComponent(<control_value>)
ExampleCustomer%20Id=merchant%201
control_id: Customer ID
control_value: merchant 1

Date picker format

TypesDatetime
FormatencodeURIComponent(<control_id>)=<control_value>
Examplestart_date=2014-05-01
control_id: start_date
control_value: 2014-05-01
Examplestart_time=2014-05-01T02:00
control_id: start_time
control_value: 2014-05-01T02:00

Date range format

TypesDatetime
FormatencodeURIComponent(<control_id>)=min:<min_date>,max:<max_date>
ExampleAnalysis%20Time%20Frame=min:2020-04-01,max:next-day-7
control_id: Analysis Time Frame
min_date: 2020-04-01
max_date: next-day-7
ExampleAnalysis%20Time%20Frame=min:2020-04-01,max:
control_id: Analysis Time Frame
min_date: 2020-04-01
max_date: null, so there is no end date.
ExampleAnalysis%20Time%20Frame=min:2020-04-01,max:next-day-7
control_id: Analysis Time Frame
min_date: prior-year-0, or the start of the current year
max_date: 2020-04-01T02:00
Notes<min_date> and <max_date> are either exact ISO dates, or a relative date(<date_type>_<date_unit>_<date_number>)

Value list format

TypesText, Number, Datetime
FormatencodeURIComponent(&lt;control_id&gt;)=encodeURIComponent(&lt;control_value1&gt;)[,encodeURIComponent(&lt;control_value2&gt;)…]
ExampleEmployee%20Name=Greg%20Humphrey
control_id: Employee Name
control_value: Greg Humphrey
ExampleEmployee%20Name=Greg%20Humphrey,Xiaoyu%20Xu,Meera%20Deshpande
control_id: Employee Name
control_value1: Greg Humphrey
control_value2: Xiaoyu Xu
control_value3: Meera Deshpande
Examplebirthday=1970-05-01,1991-01-24
control_id: birthday
control_value1: 1970-05-01
control_value2: 1991-01-24
NotesFor Text and Number examples, <values> is a list of comma-separated URL encoded values.
For Datetime examples, <values> is a list of comma-separated ISO Dates. Datetime does not support URL-encoded values.

Number range format

TypesNumber
FormatencodeURIComponent(&lt;control_id&gt;)=min:&lt;min_value&gt;,max:&lt;max_value&gt;
ExampleUser%20Revenue=min:4000.5,max:
Any value greater than 4000.5
ExampleUser%20Revenue=min:4000.5,max:5000
Any value between 4000.5 to 5000

Checkbox and switch format

TypesLogical
FormatencodeURIComponent(&lt;control_id&gt;)=true,false
Exampleis_weekend=true,false
Exampleis_weekend=true
Exampleis_weekend=false

Simple text box example

A text box the most basic control in Sigma, where the control is just a single value.  For example, you can update the control to have the value merchant 1.

Looking from the control format above, you know that the URL encoding is: 

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

control_id is the ID. 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, you need to encode the space to be URL safe using %20.

Date range details

The format is:

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

Where min_date / max_date is an exact date (ISO Date), or blank or :null to clear out a pre-selected date, or a relative dates (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

For example:

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

Sets the min date as 2020-04-01 and the max as 7 days in the future. If the <min_date> or <max_date> is empty, that means that there is no date set.

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

Sets the date to any time after 2020-04-01.

Analysis%20Time%20Frame=min:,max:

Has no min or max dates set. You can use this to clear out a pre-selected date in the control.

Any relative format for min_date is the start of the date. For example, prior-year-1 means the start of the previous year and next-year-0 would mean the start of the current year.

Any relative format for max_date is the end of the date. For example, next-year-1 means the end of the next year and next-year-0 means the end of the current year.