Pass parameter values via query string

Contents[Hide]

1. Overview

When embedding a view such as a dashboard inside another application (e.g., iframe), you can pass parameter or filter values via query string instead of having to serialize them and use a short link service. This method simplifies the process of parameter passing and there is also the benefit of the parameter values being more human-readable.

2. Base URL

In terms of embedding, there is a base URL that you need to construct which consists of the Dundas BI server address, a dashboard identifier, and the viewer options (passed by query string).

For example, a base URL for embedding a dashboard might be:

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

The base URL for embedding a scorecard or report will be similar. Just replace the "/Dashboard/" portion with "/Scorecard/" or "/Report/" and append the appropriate ID.

Note that the base URL above already uses a query string to pass in the view options. Depending on the method of integration or embedding you may also need to pass in other values by query string such as a sessionId or a logonTokenId.

3. Append parameter values

To pass in parameter values you 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):

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

So the syntax for adding a 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 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. 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.4. Custom attributes

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

4.5. 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 Dundas BI 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 add a Member filter control (attached to a chart for example) to your dashboard and use the network capturing capability built into your browser. Switch to View mode and expand/collapse items in the Member filter. Then go to Chrome Developer tools, for example, to examine the Network XHR data.

Get the unique name for Year 2007 member
Get the unique name for Year 2007 member

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

Token TypeTokenShorthand name
Basic All $*$
  Default $D$
  Null $N$
  Open Range $OR$
  No Selection $NoSel$
Date Range Today $Today$
  Current Year $CY$
  Current Quarter $CQ$
  Current Month $CM$
  Current Week $CW$
  Current Day $CD$
  Previous Year $PY$
  Previous Quarter $PQ$
  Previous Month $PM$
  Previous Week $PW$
  Previous Day $PD$
  Year To Date $YTD$ 
  Quarter To Date $QTD$
  Month to Date $MTD$
Single Date Beginning of Current Year $BOCY$
  Beginning of Current Quarter $BOCQ$
  Beginning of Current Month $BOCM$
  Beginning of Current Week $BOCW$
  Beginning of Current Day $BOCD$
  End of Current Year $EOCY$

6. Examples

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

Scenarios

TypeSample (what to append to base URL)
Date range &$dateParam=2005-07-14~2005-07-16
Data cube promoted hierarchy &$prodParam=709.A.Product
OLAP date member &$dateParam=[Delivery%20Date].[Date].%26[20061018]
OLAP date member & collection of dimension members &$dateParam=[Delivery%20Date].[Date].%26[20061018]&$countryParam=[Geography].[Geography].[Country].%26[Canada]|[Geography].[Geography].[Country].%26[France]
Default value for view parameter &$viewParameter1=$D$

Single Date filter

TypeSample
Set a date (Sept 7, 2007) and time (00:00) &$viewParameter1=2007-09-07T00:00:00.000Z (use UTC datetime format)
Set the date portion only &$viewParameter1=2007-09-07
Set the date to the Today token &$viewParameter1=$Today$
Set to a value from the default time dimension hierarchy &$viewParameter1=0.20070918.0.54320

Note
The '54320' value that you see in the sample is part of the unique name for members of the default time dimension hierarchy.

Range Date filter

TypeSample
Set a date range (May 01, 2006 to Oct 15, 2007) &$viewParameter1=2006-05-01~2007-10-15
Set the date range to the Previous Year token &$viewParameter1=$PY$
Set the Open Range token on lower boundary &$viewParameter1=$OR$~2007-10-15
Set range values from the default time dimension hierarchy &$viewParameter1=0.20070215.0.54320~0.20070825.0.54320

Calendar filter with implicit datetime hierarchy

TypeSample
Set to a specific day &$viewParameter1=0.20070918.0.54320
Set to a specific month &$viewParameter1=2.2006.07.2.54320
Set to a specific year &$viewParameter1=5.2007.5.54320
Set to the Previous Year token &$viewParameter1=$PY$

Calendar filter with explicit time hierarchy

TypeSample
Set to a specific day &$viewParameter1=0.20070918.0.54320.OrderDate
Set to a specific month &$viewParameter1=2.2006.09.2.54320.OrderDate
Set to a specific year &$viewParameter1=5.2007.5.54320.OrderDate
Set to the Previous Year token &$viewParameter1=$PY$

Calendar Range filter with implicit datetime hierarchy

TypeSample
Set to the Today token &$viewParameter1=$Today$
Set to a specific date range &$viewParameter1=0.20070215.0.54320~0.20070825.0.54320
Set to a range of single date tokens &$viewParameter1=$BOCY$~$EOCY$

Calendar Range filter with explicit time hierarchy

TypeSample
Set to the Today token &$viewParameter1=$Today$
Set to a specific date range &$viewParameter1=0.20070215.0.54320.OrderDate~0.20070825.0.54320.OrderDate
Set to a range of single date tokens &$viewParameter1=$BOCY$~$EOCY$

Single Number filter

TypeSample
Set to a numeric value &$viewParameter1=2500568.36
Set to the Null token &$viewParameter1=$N$

Range Number filter

TypeSample
Set to a numeric range &$viewParameter1=2000~3000
Set the Open Range token on upper boundary &$viewParameter1=2500~$OR$

Slider filter

TypeSample
Set to a numeric range &$viewParameter1=2500~3700

Level filter

TypeSample
Set to a level number &$viewParameter1=1

Member filter

TypeSample
Set to the 'All' token &$viewParameter1=$*$
Set to two members &$viewParameter1=1.A.ProductID|2.A.ProductID
Set to three members &$viewParameter1=1.B.ProductID|2.B.ProductID|3.B.ProductID

Member Range filter

TypeSample
Set to the 'All' token &$viewParameter1=$*$

Cascading Member filter

TypeSample
Set the unique name of the value in the lowest level &$viewParameter1=752.C.ProductID

Checkbox filter

TypeSample
Set to True &$viewParameter1=True
Set to False &$viewParameter1=False
Set to True &$viewParameter1=1
Set to False &$viewParameter1=0

Checkbox List filter with implicit hierarchy

TypeSample
Check two values &$viewParameter1=ColonialVoice.CardType|Vista.CardType

Checkbox List filter with explicit hierarchy

TypeSample
Check two hierarchy values &$viewParameter1=4.A.ProductID|2.A.ProductID

Dynamic Element filter

TypeSample
Name of the hierarchy/measure to display &$viewParameter1=LineTotal

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.

TypeSample
Backward 3 years (‘5’ is year level) &$viewParameter1=-3|5.54320.OrderDate
Forward 4 months (‘2’ is month level) &$viewParameter1=4|2.54320.OrderDate
Backward 7 days (‘0’ is day level) &$viewParameter1=-7|0.54320.OrderDate
Backward 3 years (‘5’ is year level) &$viewParameter1=-3~5.54320.OrderDate
Forward 4 months (‘2’ is month level) &$viewParameter1=4~2.54320.OrderDate
Backward 7 days (‘0’ is day level) &$viewParameter1=-7~0.54320.OrderDate

7. Notes and limitations

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

8. See also

Dundas Data Visualization, Inc.
500-250 Ferrand Drive
Toronto, ON, Canada
M3C 3G8

North America: 1.800.463.1492
International: 1.416.467.5100

Dundas Support Hours: 7am-6pm, ET, Mon-Fri