416.467.9100 | Dundas Data Visualization | Login
Welcome Guest
Dashboard v5.0

This site makes extensive use of JavaScript.

Please enable JavaScript in your web browser and reload the page before proceeding.

Using the Token Designer

Hide navigation
RSS
Modified on Tue, 03 Jun 2014 03:56 PM Categorized as Administration
Click to return to: Documentation | Dundas Dashboard Administration


Overview

Tokens are used in Dundas Dashboard as a means of simplifying user input. On a dashboard, you can access the token menu of a parameter control and use it to select standard filter values such as All Values or Null. For time dimension filters, additional tokens let you select relative date values such as Today, Current week, or Year to date.

Token menu.

Token menu.


Dundas Dashboard administrators can rename the built-in tokens which are included with the application or create new custom tokens such as Last 40 days or Current Quarter. Tokens can also be hidden to reduce the number of items displayed in the token menu.

Custom token Last 40 days.

Custom token Last 40 days.


Double-click Token Designer in the Administration sidebar to launch a designer screen that lets you modify built-in tokens or create new ones.

The Token Designer screen.

The Token Designer screen.


Note: If you are using client or server-side memory caching, and then apply a custom token at viewing-time, the results will be cached along with the token definition. These cached results will still be returned if you subsequently modify the custom token via the Token Designer. Thus, to avoid returning incorrect results, it is recommended to clear the client and server caches after modifying a custom token, or create a new token instead of modifying one that has already been used. (You can use the invalidateDataCache command-line utility in the Tools folder to invalidate the server-side cache.)

Background

Global and project tokens

Tokens can be scoped to a single Dundas Dashboard project, or accessed globally across the application instance. The built-in tokens included with Dundas Dashboard are all global tokens. You can use the Filter by project dropdown list in the Token Designer to filter the list of tokens accordingly.

Filter tokens by project.

Filter tokens by project.


Token types

Tokens are classified into different types according to how they are defined.

Token TypeDescriptionExample
Built-inA predefined token included with Dundas Dashboard.Beginning of current year
CombinationA token defined using a combination of built-in tokens.
Suitable for single value or full range scenarios.
The Day Before Yesterday = Today - 2
Script-basedA token defined using DundasScript expressions,
allowing unlimited flexibility.
DateTime[] result = new DateTime[2];
result[0] = DateTime.Today.AddDays(-1);
result[1] = DateTime.Today;
return result;
Explicit valueA token defined using fixed string, number, or date values.Company Holiday = May 1, 2012
Named setA token defined on a specific dimension hierarchy,
using a preset member selector, custom SQL/MDX
expressions, or existing virtual table.
North America = Canada, U.S.A., Mexico
Time dimension-basedA token defined using a time dimension calendar
(Gregorian, Fiscal, or ISO 8601).
Previous Fiscal Year

You can use the dropdown list in the Token Designer to filter the list of tokens by type.

Filter tokens by type.

Filter tokens by type.


Range types

A token can represent a single numeric/date value, or a range of numeric/date values. For example, the predefined Now token is a single value token, whereas Current year is a range token.

Range TypeExamples
Single ValueNow
Beginning of today
Beginning of previous year
Range StartNow
Beginning of today
Beginning of previous year
Range EndEnd of today
End of current year
End of previous month
Full RangeToday
Current week
Current year
Month to date

Stored procedures

If your dashboard parameter is based on a stored procedure and the parameter data type is Date, use the Single Value range type when defining your custom token.

Creating a new token

To define a new custom token:

  1. Click New Token at the bottom of the Token Designer screen.
    New Token button.
  2. In the Parameter Token Setup wizard, enter a Name for the token.
  3. Optionally add a Description for the token.
    Token name and description.
  4. By default, the scope of the new token will be global. If you want to have a project-specific token, select the Project specific token check box, and then use the dropdown list to select an existing Dundas Dashboard project.
    Token project.
  5. Choose a token type, and then click Next to define the token. The remaining steps are different in each case. See the sections that follow for more detail.
    Choose token type.

Combination token

To define a combination token:

  1. Select the Range type.
  2. Select the Token value.
  3. Enter an Offset if applicable. This will be an integer value that has the same units as the token value. For example, if the token value is Current year, then the offset will be in years as well.

Defining a combination token.

Defining a combination token.


As another example, the figure below shows how to define a Last 40 days token by using a combination of built-in tokens plus offsets.

Defining a Last 40 days token.

Defining a Last 40 days token.


Note: Not all built-in tokens support offsets. For example, offsets are not applicable to All Values, Now, Month to date, and Year to date.

Script-based token

To define a script-based token:

  1. Select the Data type from these choices:
    • Date
    • Numeric
    • String
  2. Select the Range type.
  3. The script editing area contains an initial script to get you started. It has examples for different data and range types. You can uncomment the appropriate section in the initial script and customize it as needed. For more details on scripting, see Scripting in Dundas Dashboard.

Tip: Toggle the Explorer in the script editor to see the objects and types that are available for scripting tokens. For example, the currentSession object provides properties that you can use for filtering based on the current user.

Defining a script-based token.

Defining a script-based token.


Using explicit values

To define a custom token using explicit values:

  1. Select the Data type from these choices:
    • Date
    • Numeric
    • String
  2. Select the Range type.
  3. Enter the Token value using controls appropriate for the data type. For example, use calendar and time controls to set a precise date for Date tokens.

Defining a custom token using explicit values.

Defining a custom token using explicit values.


Named set token

Named set tokens must be project-specific. The chosen project must also have access to a dimension hierarchy (⪚ from a virtual cube or a standard relational dimension).

If you are defining a named set token for filtering on a KPI/dataset dimension, you should ensure that the KPI/dataset filter allows multiple selection. Otherwise, the named set token will not be available in the parameter control's token menu.

To define a named set token, you must select a dimension hierarchy as follows:

  1. Select a virtual cube (or relational dimension) from the top list.
  2. Select an available dimension hierarchy from the bottom list.
  3. Click Next.

Select dimension hierarchy.

Select dimension hierarchy.


Next, select the type of named set from these options:


Preset member selection

To define a named set token using preset member selection, click the Preset values button to choose specific members.

Using preset member selection to define a named set token.

Using preset member selection to define a named set token.


Custom SQL/MDX expression

To define a named set token using a custom SQL/MDX expression, customize the sample SQL/MDX expression as needed to select the desired members.

Using a custom MDX expression to define a named set token.

Using a custom MDX expression to define a named set token.


Using a custom SQL expression to define a named set token.

Using a custom SQL expression to define a named set token.


Virtual table column

This option lets you specify a virtual table column that will provide members for the named set token at a certain hierarchy level. For example, if you have a relational Geography dimension hierarchy with a Country level, you can specify a virtual table column that will provide the country values.

Using a virtual table to define a named set token.

Using a virtual table to define a named set token.


Tip: If the virtual table is based on a stored procedure or manual SQL query, you can add a user-based parameter that allows the results of the virtual table to be automatically filtered depending on the logged-in user. Thus, when a user applies the named set token while viewing a dashboard, the members returned will actually be dependent on that user. For more details, see Using Custom Attributes.

Time dimension-based token

The following example shows how to define a time dimension-based token, Previous Fiscal Year, which starts in March:

  1. Set the Range type to Full Range.
  2. Set the Calendar type to Fiscal. (Other choices are Gregorian and ISO 8601.)
  3. Click the First day of the week dropdown list and choose the starting day of your week (⪚ Sunday).
  4. Set the Start month to March.
  5. If you want the calendar to use the Calendar year + 1 naming convention, select the check box provided.
  6. Set the Start value to Year and its Offset to -1.
  7. Set the End value to Year and its Offset to -1.
  8. Click Finish.

Defining a time dimension-based token.

Defining a time dimension-based token.


You can now use the Previous Fiscal Year token to filter data on a dashboard.

Using a time dimension-based token.

Using a time dimension-based token.


Managing tokens

Editing a token

To edit an existing token:

  1. Locate the token in the list and click the Edit button in the Action column.
    Edit an existing token.
  2. For built-in tokens, you will be able to rename the token, change its description, or add localized names for the token.
    Edit a built-in token.

Deleting a token

To delete a custom token:

  1. Locate the token in the designer list.
  2. Click the corresponding Delete button in the Action column.
    Delete an existing token.
  3. When prompted to confirm the deletion, click Yes.

Refreshing the list of tokens

To refresh the list of tokens in the Token Designer, click Refresh at the bottom of the screen.

Localizing tokens

When you edit or create a new token, click Localize to specify a localized token name for each available language/culture that is listed.

Localizing a token.

Localizing a token.


For more details on localization, see Multi-Language Support in Dundas Dashboard.

Showing or hiding tokens

When a token is hidden, it won't be available in the token menu of a parameter control.

You can hide a token in the Token Designer list by selecting the corresponding check box in the Hidden column.

Or, you can quickly hide multiple tokens by selecting several rows in the list, and then click Hide Selected at the bottom of the designer.

Hiding selected tokens.

Hiding selected tokens.


To unhide (&ie; uncheck) multiple tokens, select the corresponding rows, and then click Unhide Selected at the bottom of the designer.

Notes

Various notes or limitations:


Related topics


Click to return to: Documentation | Dundas Dashboard Administration

About Dundas | Contact Us Follow us on Twitter! | Privacy Statement | Report Site Issues

Copyright © 2009-2014 Dundas Data Visualization, Inc.