Dashboards can be enhanced through the effective use of URL parameters. A URL parameter is a property that is added to a dashboard's configuration by its author that can be used to trigger actions. In doing so, URL parameters allow the dashboard to be displayed in a prescribed way. URL parameters are also useful when a dashboard is embedded in another app. In this scenario, you can use the hosting app to change the current view of the dashboard.
Learn how to configure actions on URL parameters
Note:
With the exception of the built-in locale parameter, changing a dashboard's parameters at run time will not cause it to reload in most modern browsers.
A URL parameter is a name-value pair. In each parameter, the name and value are separated by an equal sign (=). At run time, you can add a parameter to the end of a dashboard's URL using a hash (#), followed by the parameter.
For example, a dashboard URL containing a parameter could be <scheme>://<yourURL>/apps/dashboards/<id>#param=value.
For multiple parameters, add an ampersand (&) between each: <scheme>://<yourURL>/apps/dashboards/<id>#param=value¶m2=value2
Tip:
The order of the parameters does not matter. For example, param=value¶m2=value2 and param2=value2¶m=value produce the same result.Parameter names are composed of ASCII alphanumeric characters. The dash (-) and underscore ( _ ) are also permitted, in any position other than the first. Invalid characters are blocked at design time with a validation warning. As a best practice, avoid using long parameter names.
Note:
Some parameter names are reserved by the dashboard, for example, mode and edit. When creating a parameter, an Already used validation warning occurs if you use a reserved name.
Caution:
URL parameters and selectors are both used to provide interaction between dashboard elements. When used to target the same elements, they can contradict one another and cause unexpected results. Take care when designing your dashboard's interactions.URL encoding
When passing a parameter to a dashboard at run time, make sure to encode its value. Encoding ensures that invalid characters are replaced with % followed by their hexadecimal equivalent. For example, the following passes the value Main Street via a URL parameter:<scheme>://<yourURL>/apps/dashboards/<id>#param=Main%20Street
When passing a URL parameter as a comma separated list of values, keep the following in mind:
- Encode each value separately.
Correct
param=Main%20Street,Broadway%20AvenueIncorrect. Do not encode the comma used to separate values.
param=Main%20Street%2CBroadway%20Avenue - Do not include spaces between values.
Correct
param=Main%20Street,Broadway%20AvenueIncorrect
param=Main%20Street, Broadway%20Avenue
URL parameter types
There are five types of URL parameters: category, numeric, date, feature, and geometry. For information on the types of actions that can be triggered by the various parameter types, see Configuring actions on URL parameters.
Category parameter
You can use a category parameter to apply a filter action to one or more elements. At design time, specify the parameter's name, whether inputs will be of type string or number, and whether filter queries will include or exclude the passed in values.
At run time, category parameters accept either a single value or multiple values separated by a comma. Do not include a space after the comma.
When a single value is passed in, the query uses the comparative operator equal or not equal to filter the target elements. When multiple values are passed in, the logical IN or NOT IN operators are used.
Examples
The following table indicates whether the category parameter is configured to expect a string or a number:
| Parameter | Note |
|---|---|
| status=DAMAGED | String |
| status=DAMAGED,DESTROYED | String with multiple values |
| category=1 | Number |
| category=1,2 | Number with multiple values |
Special case examples
Data categories are not always set, or in the case of strings, may be empty. As a result, category parameters support the following four special cases:
- ((null))
- ((notnull))
- ((empty))
- ((notempty))
| Parameter | Note |
|---|---|
| status=((null)) | Filter for values that are NULL. |
| status=((notnull) | Filter for values that are NOT NULL. |
| status=((empty)) | Filter for values that are empty. |
| status=((notempty)) | Filter for values that are not empty. |
| status=DAMAGED,((null)) | Filter for value passed in, OR are NULL. |
| status=DAMAGED,DESTROYED,((null)) | Filter for multiple values passed in, OR are NULL. |
Numeric parameters
You can use numeric parameters to apply a filter action on one or more target elements. At design time, specify the parameter's name and whether the expected input values will be a single value or two values that represent a range. When a single value is used, the parameter is configured to apply one of the following comparison operators:
- equal
- not equal
- less than
- less than or equal
- greater than
- greater than or equal
Tip:
To gain finer control than what the range value type offers, create two single numeric parameters and apply the filter condition (operator) that meets your requirements. At run time, the single parameters are combined with a logical AND operator when applying a filter to the target elements.
At run time, numeric parameters are passed in as a single value or two values separated by a comma.
Examples
The following table indicates whether the numeric parameter is configured to expect a single value or a range:
| Parameter | Note |
|---|---|
| meas=10 | Single value |
| meas=10,15 | Range |
Special case examples
Numeric values in data are not always set. As a result, numeric parameters support two special cases: ((null)) and ((notnull)). You can use these special case labels in both single value and numeric range scenarios.
| Parameter | Note |
|---|---|
| meas=((null)) | Single date value or numeric range. Filter for values that are NULL. |
| meas=((notnull)) | Single date value or numeric range. Filter for values that are NOT NULL. |
| meas=10,((null)) | Single value. Filter for value OR for values that are NULL. |
| meas=10,15,((null)) | Numeric range. Filter for numbers in range OR for values that are NULL. |
Another special case is when a numeric parameter expects a range, but only a single value is provided at run time.
| Parameter | Note |
|---|---|
| meas=,10 | Open-ended left. Values less than or equal to this value are filtered. |
| meas=10, | Open-ended right. Values greater than or equal to this value are filtered. |
| meas=10 | Open-ended right. Values greater than or equal to this value are filtered. |
| meas=10,((null)) | Open-ended right. Filter values greater than or equal to this value OR are NULL. |
Date parameters
You can use date parameters to apply a filter action on one or more target elements. At design time, specify the parameter's name and whether the expected input values will be ISO 8601 date strings or UNIX Epoch.
You can configure date parameters to process a single value or two values that represent a date range. When a single value is used, the parameter is configured to apply one of the following comparison operators:
- is
- is not
- is before
- is or is before
- is after
- is or is after
Tip:
To gain finer control than what the range value type offers, create two single date parameters and apply the filter condition (operator) that meets your requirements. At run time, the single date parameters are combined with a logical AND operator when applying a filter to the target elements.At run time, date parameters are passed in as a single value or two values separated by comma. When a date parameter is UNIX Epoch, it must be a signed 32-bit integer. When it's a string, dates must be formatted as YYYY-MM-DD or YYYYMMDD. Dates are entered using the Gregorian calendar and are composed of years, months, and days.
- YYYY—Four-digit year (YYYY)
- MM—Two-digit month of the year (01 through 12)
- DD—Two-digit day (01 through 31)
Tip:
The list of date formats supported by date parameters is different than those supported by the serial chart for parsing dates.
A time part can also be included with a date. Times are entered using a 24-hour clock and are composed of hours, minutes, and seconds. You can format them as hh:mm:ss or hhmmss. If no time part is included with the date, the entire day between 00:00:00 and 23:59:59 is implied.
- hh—A zero-padded hour between 00 and 24
- mm—A zero-padded minute between 00 and 59
- ss—A zero-padded second between 00 and 59
If specified, the time part is separated from the date part by a space or an uppercase T. The following are valid dates passed as strings:
| Date | Note |
|---|---|
2018-10-31 | Date only |
20181031 | Date only (alternate format) |
2018-10-31T23:14:42 | Date and time separated by T |
20181031T231442 | Date and time separated by T (alternate format) |
2018-10-31 23:14:42 | Date and time separated by space |
20181031 231442 | Date and time separated by space (alternate format) |
Tip:
Separating a date and time with an uppercase T is recommended. If you use a space, encode it.
When dates are passed to a dashboard at run time, their time component is assumed to be specified in the local time zone—that is, the time zone of the machine or device on which the browser is running. For additional control, you can also specify time as coordinated universal time (UTC) or as an offset from UTC. To indicate that time is in UTC, add the letter Z directly after the time without a space. The Z is the zone designator for the zero UTC offset. An offset from UTC is appended to the time in the form ±hh:mm, ±hhmm, or ±hh.
| Date | Note |
|---|---|
2018-10-31T23:14:42Z | UTC |
2018-10-31T23:14:42+01:00 | One hour ahead of UTC |
2018-10-31T23:14:42+0100 | One hour ahead of UTC |
2018-10-31T23:14:42+01 | One hour ahead of UTC |
2018-10-31T23:14:42-05:00 | Five hours behind UTC |
2018-10-31T23:14:42-0500 | Five hours behind UTC |
2018-10-31T23:14:42-05 | Five hours behind UTC |
When constructing filters from date parameters, dashboards examine the target element's data source for time zone information. If found, queries are sent in that time zone. If time zone information is not found, the target data source is assumed to be UTC. In either case, the dashboard may need to convert input times to match that of the target.
Tip:
If a dashboard receives a date parameter in a format it does not recognize, it is ignored at run time.Examples
In the following table, notes indicate whether the date parameter is configured to expect a single date or a date range. UNIX Epoch and date string examples are provided.
| Parameter | Note |
|---|---|
| created=1541027682 | Single value using UNIX Epoch. |
| created=2018-10-31 | Single value using date string, with full day implied. |
| created=2018-10-31T23:14:42 | Single value using date string with time. Local time zone use is implied. |
| created=2018-10-31T23:14:42Z | Single value using date string with time in UTC. |
Special case examples
Date values are not always set. Consequently, date parameters support two special cases: ((null)) and ((notnull)). These special case labels can be used in both single value and date range workflows.
| Parameter | Note |
|---|---|
| created=((null)) | Single date value or date range. Filter for NULL dates. |
| created=((notnull)) | Single date value or date range. Filter for dates that are NOT NULL. |
| created=2018-10-31,((null)) | Single date value. Filter for October 31, OR dates that are NULL. |
| created=2018-10-31,2018-11-05,((null)) | Date range. Filter dates in range, OR dates that are NULL. |
Another special case is when a date parameter expects a range, but only a single value is provided at run time.
| Parameter | Note |
|---|---|
| created=,2018-10-31 | Open-ended left. Dates on or before will be filtered. |
| created=2018-10-31, | Open-ended right. Dates on or after will be filtered. |
| created=2018-10-31,((null)) | Open-ended right. Filter dates on or after, OR dates that are NULL. |
Feature parameters
Feature parameters are used to pass one or more feature IDs to a dashboard. They can be used to filter the dashboard's elements, or they can be used to apply location actions—Zoom, Pan, Show pop-up, and Flash—to the dashboard's maps.
At design time, specify the parameter's name and select a data source. The data source's unique ID field must be identified. Failure to select a field that contains non-unique values leads to unexpected behavior at run time.
Tip:
If the selected data source contains polygons, it can be used to apply spatial filters to target elements.At run time, be sure to URL encode feature IDs if the values in the target layer are strings. Multiple feature IDs can be passed in by separating them with commas, for example, #asset=1240,1241,1242. Do not include a space after each comma.
Examples
| Parameter | Note |
|---|---|
| id=11033 | Single value |
| id=11033,23034,34035 | Multiple values |
Geometry parameters
There are two types of geometry parameters: point and extent. When the type is point, geometry parameters are used to zoom to, pan to, or flash a location on one or more of the dashboard's maps. When the type is extent, you can use geometry parameters to either set a dashboard's map extents or filter its other elements. At design time, specify the parameter's name and select the geometry type before you configure any actions.
At run time, all geometry coordinates are passed in as comma-separated World Geodetic System 1984 (WGS84) values. For point parameters, the format is x,y. For extent parameters, the format is leftX,leftY,rightX,rightY. In all cases, there is no space after the comma.
Examples
| Parameter | Note |
|---|---|
| pt=-75.6971931,45.4215296 | Geometry parameter expects a point |
| ext=-80.6,40.6,-70.7,47.7 | Geometry parameter expects an extent |
Switch locale
Dashboards have a built-in URL parameter, called locale, for switching the language, number, and date formats when displaying content. Add the #locale=<language code> parameter to the end of the dashboard URL. This built-in parameter can be used in conjunction with any author-configured URL parameter by separating multiple URL parameters with an ampersand (&).
The following table lists the supported language codes:
| Language code | Language |
|---|---|
ar | Arabic |
bs | Bosnian |
ca | Catalan |
cs | Czech |
da | Danish |
de | German |
el | Greek |
en | English |
es | Spanish |
et | Estonian |
fi | Finnish |
fr | French |
he | Hebrew |
hr | Croatian |
hu | Hungarian |
id | Indonesian |
it | Italian |
ja | Japanese |
ko | Korean |
lt | Lithuanian |
lv | Latvian |
nb | Norwegian Bokmål |
nl | Dutch |
pl | Polish |
pt-br | Portuguese (Brazil) |
pt-pt | Portuguese (Portugal) |
ro | Romanian |
ru | Russian |
sk | Slovak |
sl | Slovenian |
sr | Serbian |
sv | Swedish |
th | Thai |
tr | Turkish |
uk | Ukranian |
vi | Vietnamese |
zh-cn | Chinese (Simplified) |
zh-hk | Chinese (Traditional Hong Kong) |
zh-tw | Chinese (Traditional Taiwan) |
The following is a list of locales to set the number and date format:
| Locale | Number and date format |
|---|---|
en-au | English (Australia) |
en-ca | English (Canada) |
en-gb | English (Great Britain) |
es-es | Spanish (Spain) |
es-mx | Spanish (Mexico) |
fr-ch | French (Switzerland) |
de-ch | German (Switzerland) |
it-ch | Italian (Switzerland) |
The following URL is an example of specifying the French-Switzerland locale:
<scheme>://<yourURL>/apps/dashboards/4f539791b2f1418cb5403891f1a7be50#locale=fr-ch