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.
Contents
Append a URL with a control's value
Open settings for the control you want to update through the URL
Application embedding and the URL
Append a URL with a control's 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 that, follow the steps below.
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. You can't use some characters in the URL address as they are, so if Certain characters can't be present in URLs, so if your control ID or control values contain special characters, you must use their encoded form instead. For example, the code for space is %20
. See the list of all Special characters for URL parameters.
Notes
You may use “:null” as a special value that denotes the null primitive value.
You may use “:empty” as a special value that denotes the empty string “”.
For date values, by default our system will parse these as being in your Sigma organization's Account Time Zone. You may override this behavior so that our system parses the date value as being in the UTC +0 time zone. To do so, append a "Z" at the end of the timestamp (representing the Zulu Time Zone). Example: 2023-06-08T00:00:00Z
Formats
- Textbox
-
- Types
- Text, Number
- Format
-
encodeURIComponent(<control_id>)=encodeURIComponent(<control_value>)
- Example
-
Customer%20Id=merchant%201
- control_id
- Customer ID
- control_value
- merchant 1
- Date picker
-
- Types
- Datetime
- Format
-
encodeURIComponent(<control_id>)=<control_value>
- Example 1
-
start_date=2014-05-01
- control_id
- start_date
- control_value
- 2014-05-01
- Example 2
-
start_time=2014-05-01T02:00
- control_id
- start_time
- control_value
- 2014-05-01T02:00
- Date range
-
- Types
- Datetime
- Format
-
encodeURIComponent(<control_id>)=min:<min_date>,max:<max_date>
- Example 1
-
Analysis%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, or the end date is 7 days in the future
- Example 2
-
Analysis%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. This time frame is any day after 2020-04-01.
- Example 3
-
Analysis%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
- 020-04-01T02:00
- Notes
- <min_date> and <max_date> are either exact ISO dates, or a relative dates (<date_type>_<date_unit>_<date_number>)
- Value list
-
- Types
- Text, Number, Datetime
- Format
-
encodeURIComponent(<control_id>)= encodeURIComponent(<control_value1>)[,encodeURIComponent(<control_value2>)…]
-
encodeURIComponent(<control_id>)= <control_value1[,<control_value2>…]
- Example 1
-
Employee%20Name=Greg%20Humphrey
- control_id
- Employee Name
- control_value1
- Greg Humphrey
- Example 2
-
Employee%20Name=Greg%20Humphrey,Amber%20Cullen,James%20Smith
- control_id
- Employee Name
- control_value1
- Greg Humphrey
- control_value2
- Amber Cullen
- control_value3
- James Smith
- Example 3
-
birthday=1970-05-01,1991-01-24
-
birthday=1991-01-24
- Notes
- For 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
-
- Types
- Number
- Format
-
encodeURIComponent(<control_id>)=min:<min_value>, max:<max_value>
- Example 1
-
User%20Revenue=min:4000.5,max:
Any value greater than 4000.5 - Example 2
-
User%20Revenue=min:4000.5,max:5000
Any value between 4000.5 to 5000
- Checkbox and switch
-
- Types
- Logical
- Format
-
encodeURIComponent(<control_id>)=true,false
- Example 1
-
is_weekend=true,false
- Example 2
-
is_weekend=true
- Example 3
-
is_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 are blank/: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
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. 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.
Analysis%20Time%20Frame=min:,max:
would mean no min or max dates are set. This can clear out a pre-selected date in the control.
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.
Application embedding and the URL
If you implemented legacy application embedding, you can inject the values into the URL during the server-side url generation process using <control_id> and <control_value>.
Related resources