Pass parameter values via query string

1. Overview

When embedding a view such as a dashboard or report inside another application (e.g., via an iframe or WebView), you can pass parameter or filter values via URL query string parameters. There are also query string parameters that can be passed when embedding other pages.

This is an alternative to creating a short link to use that serializes the parameter values. Passing parameters through the URL can be simpler, and there is the benefit of the parameter values being more human-readable.

2. Base URL

When embedding or linking to a view, there is a base URL to construct that consists of the server address, the file type that you want to embed, its ID, and the view options (passed via the query string).

For example, if Dundas BI or Logi Symphony's Managed Dashboards & Reports can be accessed at https://symphony.example.com/managed, a base URL for embedding a dashboard might be:

https://symphony.example.com/managed/Dashboard/092741e1-61a4-4ee8-925a-1e78a90260ad?e=false&vo=viewOnly

The base URL for embedding other view types will be similar: just replace "/Dashboard/" with "/Scorecard/", "/Report/", or "/SmallMultiple/", and append the appropriate ID. You can find the file ID in its properties.

Note that the base URL above already uses a query string to specify that edit mode is off (e=false) and pass in the view options (vo=viewonly). Depending on the method of integration or embedding you may also need to pass in other values by query string such as a logonTokenId, sessionToken, or sessionId.

3. Append parameter values

To pass in parameter values, simply append them to the query string at the end of the base URL. 

For example, if your dashboard has a Single Date filter (and associated view parameter) on an implicit date-time hierarchy, the following URL can be used to view the dashboard with the filter set to a specific date (Jan 31, 2006):

https://symphony.example.com/managed/Dashboard/092741e1-61a4-4ee8-925a-1e78a90260ad?e=false&vo=viewOnly&$viewParameter1=2006-01-31

So assuming there are already some query string parameters, the syntax for adding a view parameter value to the query string is: &$<your view parameter script name>=<your parameter value>

In the above example, the view parameter script name is viewParameter1. This is the default but you can change the script name in the Parameters window to something more descriptive such as orderDateParam or productParam, and then use this in the query string.

4. Parameter value syntax

The syntax for different types of parameter values is explained below. You can find examples for these in the Examples section.

4.1. Collection values

The | (pipe) character is used as a separator between collection values (can be used multiple times).

4.2. Range values

The ~ (tilde) character is used as a separator between two range values. Additionally, the * (asterisk) character can be prepended or appended to either or both of the range values to indicate the corresponding boundary value(s) should not be included. For example, a number range from 1 to 100 that is inclusive of boundary values can be expressed as 1~100, whereas a value of 1*~100 means to exclude the lower boundary, and a value of *1~*100 means to exclude both boundary values.

4.3. Inverted values

The ! (exclamation mark) character sign is used as a prefix to negate the indicated value. For example, viewParameter1=!2 means that viewParameter1 can be anything other than 2.

4.4. Tokens

Tokens can be used as parameter values by enclosing the token shorthand name (or its GUID) with $ (dollar sign) characters similar to placeholders. For example, a Current Year token can be expressed as: $CY$

4.5. Custom attributes

Custom attribute values can also be used as parameter values by enclosing the corresponding GUID with $ (dollar sign) characters.

4.6. Hierarchy members

Members from a time dimension hierarchy or a user hierarchy (e.g., Product) can also be used as parameter values.

For example, time hierarchy values such as 0.20070918.0.54320 or 2.2006.09.2.54320.OrderDate.

These values are the unique names of the corresponding hierarchy members which the application uses internally.

Rather than try to construct these unique names yourself, the recommended way to determine the unique name for a specific hierarchy member is to hover over it in any filter connected to that hierarchy: by filtering the hierarchy from the Data Analysis Panel, or by adding a filter connected to it. The tooltip will show the unique name.

See How to get unique name of a hierarchy member for details.

4.7. Character encoding

Since certain characters are not allowed in the query string, there will be the need to sometimes use percent-encoding. Specifically, a blank space needs to be replaced with %20. For example, to set the parameter value ‘Mountain Bikes’ use this syntax: $categoryParam=Mountain%20Bikes

5. Tokens

Token values can be referenced by GUID. For example, the Default token can be expressed as: $categoryParam=$9cb0dba7-4c9e-49cd-9383-e9bc1c5397f1$ 

But using the shorthand name of the token is easier. The following table shows the supported tokens and corresponding shorthand values.

6. Examples

This section shows a sample of what to append for different types of filters and scenarios.

Scenarios

Single Date filter

Range Date filter

Calendar filter with implicit datetime hierarchy

Calendar filter with explicit time hierarchy

Calendar Range filter with implicit datetime hierarchy

Calendar Range filter with explicit time hierarchy

Single Number filter

Range Number filter

Slider filter

Level filter

Member filter

Member Range filter

Cascading Member filter

Checkbox filter

Checkbox List filter with implicit hierarchy

Checkbox List filter with explicit hierarchy

Dynamic Element filter

Time Lag filter

The Time Lag filter can use either the pipe or tilde character as a separator, and there can be only one instance of the character.

7. Notes and limitations

• The parameter values are applied to the view before the loading event. 
• Guid tokens such as SessionId, TenantId, TimeZoneId, and AccountId are not supported.
• The Textbox filter is not supported.
• Advanced Date/Calendar Token features are not supported.
• You can filter the home screen to display only certain types of views in version 23.2 and higher using the of query string parameter, passing comma-separated values: <base url>/Home/?of=Report,Scorecard

8. See also

• Viewer integration sample
• Using the embed library
• How to get unique name of a hierarchy member
• Adding filters
• Share or export your work