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

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

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

    Incorrect

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

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. Consequently, 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

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.

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

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 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 YYYYYMMDD. 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:

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

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

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

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, 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

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, 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

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 for switching the language used when displaying content called locale. 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

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-ch

Chinese (Simplified)

zh-hk

Chinese (Traditional Hong Kong)

zh-tw

Chinese (Traditional Taiwan)

The following URL is an example of specifying the French locale:

https://<yourPortalUrl>/apps/opsdashboard/index.html#/4f539791b2f1418cb5403891f1a7be50?locale=fr

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