Back to Top

URL parameters

In this topic

  1. URL encoding
  2. URL parameter types
  3. Category parameter
  4. Numeric parameters
  5. Date parameters
  6. Feature parameters
  7. Geometry parameters
  8. Switch locale

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&param2=value2

Tip:
The order of the parameters does not matter. For example, param=value&param2=value2 and param2=value2&param=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%20Avenue

    Incorrect. 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%20Avenue

    Incorrect

    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:

ParameterNote
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))

ParameterNote
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:

ParameterNote
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.

ParameterNote
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.

ParameterNote
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:

DateNote

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.

DateNote

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.

ParameterNote
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.

ParameterNote
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.

ParameterNote
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

ParameterNote
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

ParameterNote
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 codeLanguage

ar

Arabic

bg

Bulgarian

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:

LocaleNumber 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

Feedback on this topic?

In this topic
  1. URL encoding
  2. URL parameter types
  3. Category parameter
  4. Numeric parameters
  5. Date parameters
  6. Feature parameters
  7. Geometry parameters
  8. Switch locale