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 in cases where a dashboard has been embedded into another application. In this scenario, the hosting app can be used to change the current view of the dashboard.
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, a parameter is appended to the end of a dashboard's URL using a question mark (?), followed by the parameter.
For example, a dashboard URL containing a parameter could be <scheme>://<yourPortalUrl>/apps/opsdashboard/index.html#/<id>?param=value.
For multiple parameters, an ampersand (&) is added between each: <scheme>://<yourPortalUrl>/apps/opsdashboard/index.html#/<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.
Tip:
Some parameter names have been reserved for internal use, for example, mode and edit. When creating a new parameter, an Already used validation warning will occur 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, however, 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, encode its value. Encoding ensures that invalid characters are replaced with % followed by their hexadecimal equivalent. For example, passing the value Main Street via a URL parameter would look as follows:<scheme>://<yourPortalUrl>/apps/opsdashboard/index.html#/<id>?param=Main%20Street
When passing a URL parameter as a comma separated list of values, keep the following in mind:
- Each value should be encoded separately.
Correct
?param=Main%20Street,Broadway%20AvenueIncorrect. Do not encode the comma used to separate values.
?param=Main%20Street%2CBroadway%20Avenue - There should be no 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 more information on the types of actions that can be triggered by the various parameter types, see Configuring actions on URL parameters
Category parameter
A category parameter is used to apply a filter action to one or more elements. At design time, dashboard authors 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 comma. There should be no space after the comma.
When a single value is passed in, the behind-the-scenes query executed 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
In the following table, notes are provided to indicate whether the category parameter has been 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. Consequently, 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
Numeric parameters are used to apply a filter action on one or more target elements. At design time, dashboard authors specify the parameter's name and whether the expected input values will be a single value, or two values that represent a range. When 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 will be 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
In the following table, notes are provided to indicate whether the numeric parameter has been 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. Consequently, numeric parameters support two special cases: ((null)) and ((notnull)). These special case labels can be used in both single value and numeric range workflows
| 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 will be filtered |
| ?meas=10, | Open-ended right. Values greater than or equal to this value will be filtered |
| ?meas=10 | Open-ended right. Values greater than or equal to this value will be filtered |
| ?meas=10,((null)) | Open-ended right. Filter values greater than or equal to this value OR are NULL |
Date parameters
Date parameters are used to apply a filter action on one or more target elements. At design time, dashboard authors specify the parameter's name and whether the expected input values will be ISO 8601 date strings or UNIX Epoch.
Date parameters can be configured to process a single value or two values that represent a date range. When 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 will be 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 is expecting a signed 32-bit integer. When it's a string, dates are to 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. They can be formatted as hh:mm:ssor 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. To gain some additional control, time can also be specified as coordinated universal time (UTC) or as an offset from UTC. To indicate that time is in UTC, add a 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 will be 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 will be ignored at run time.Examples
In the following table, notes are provided to indicate whether the date parameter has been configured to expect a single date or a date range. UNIX Epoch and date string examples are provided.
| Parameter | Note |
|---|---|
| ?created=1541027682 | Single value. UNIX Epoch |
| ?created=2018-10-31 | Single value. Date string. Full day implied |
| ?created=2018-10-31T23:14:42 | Single value. Date string with time. Local time zone implied |
| ?created=2018-10-31T23:14:42Z | Single value. Date string with time. 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, Follow Feature, and Flash—to the dashboard's maps.
At design time, dashboard authors 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 nonunique values will lead 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.
Tip:
If a feature parameter is configured to perform a Follow Feature action, only one ID is expected. If multiple values are passed in, only one of the features will be followed. The one that's followed does not necessarily reflect the order of the IDs passed in.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, geometry parameters can be used to either set a dashboard's map extents or filter its other elements. At design time, dashboard authors are asked to specify the parameter's name and select the geometry type before any actions are configured.
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 |
hi | Hindi |
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 |
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) |
When using English and Spanish language codes, the following locales can also be used 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) |
The following URL is an example of specifying the French locale:
https://<yourPortalUrl>/apps/opsdashboard/index.html#/4f539791b2f1418cb5403891f1a7be50?locale=fr