Workbook controls in the URL
In Sigma you can update the values of workbook controls via URLs. For each type of control there are different formats to add into the URL.
Example
When no controls are included a workbook URL the workbook uses the published workbook's selected control values and displays a URL like this:
https://app.sigmacomputing.com/embed/7ufGXlEsaTB39TSiUUkXIY
If we add a new value (2016) to Year, the URL becomes:
https://app.sigmacomputing.com/embed/7ufGXlEsaTB39TSiUUkXIY?Year=2016
?Year=2016 was appended to the end of the URL as a search parameter. This control targets all three data elements on the page, and as result each element updates to only show data from 2016.
Need to include multiple parameters and values? Simply append an "&" in between like this:
?Year=2016&Region=West,Southwest
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 that 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.
Format the value
In this step, 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.
- 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:next-day-7
- 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 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.
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 are blank/literal 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. 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.
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.
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.
Hidden Controls and the URL
Hidden controls can not be manipulated through the URL by users without Can Edit access on the workbook.
Note: If you are implementing application embedding, these values can be injected into the url during the server-side url generation process using <control_id> and <control_value>.