Creating custom tokens

Contents[Hide]

1. Overview

Custom tokens can be added to the tokens menu of filters to provide your own filtering options, based on a predefined set, a time offset, or script.

On dashboards and other views, you can access a filter's token menu and select options such as All or Null. For time dimension filters, additional tokens let you select relative date values such as TodayCurrent week, or Year to date.

Token menu
Token menu

All Dundas BI users with the Create Token privilege can create new tokens.

Custom token last 40 days
Custom token last 40 days

There are three types of custom tokens you can create:

Token CategoryDescriptionExample
Named Set A token defined on a specific dimension hierarchy USA, Canada, Paris
Relative Time Time based parameter token definition Current Week, Last 30 days, Beginning of Today
Script A token defined using DundasScript, allowing unlimited flexibility return TimeZoneInfo.ConvertTimeFromUtc(DateTime.UtcNow, currentSession.TimeZone);

2. Tokens list

To find a list of your existing tokens and to create new script and relative time tokens, click the Profile button in Dundas BI's left menu, and scroll down to find Tokens.

Access your tokens
Access your tokens

Click the action icons next to existing tokens to view details, edit, or delete.

Tokens list
Tokens list

3. Creating new tokens

3.1. Named Set token

To create a new named set token, start by selecting hierarchy member values from a filter in a metric set, or in a dashboard or other view.

Select filter values
Select filter values

From the the hierarchy filter's token menu, select Save Selection as Token....

Save Selection as Token
Save Selection as Token

Enter a Caption and click the submit button at the bottom of the dialog.

You can now find this token in the filter's token menu.

Using the Named Set Token
Using the Named Set Token

3.2. Relative Time token

In the tokens list found in your Dundas BI profile, click the Relative Time Token button to create a new relative time token.

In the New Relative Time Token dialog, enter a Caption for the token.

For a relative time token, the data type is locked to Date and Time Hierarchy.

Data Type
Data Type

Select the Display Type. For our "Last 40 days" example, we select Range Full since it defines both a start and and end to a filter range.

Display Type
Display Type

If desired, set Format Override to display date values in a particular format in filters with this token selected.

Token format override
Token format override

Depending on what Display Type was chosen, select granularity and offset for the start and/or end of the range.

Start member granularity
Start member granularity

End member granularity
End member granularity

Click the submit button to create the token and return to the updated tokens setup screen. The new token can now be found in the tokens menus for calendar and date/time filters.

Last 40 days token
Last 40 days token

3.3. Script token

In the tokens list found in your Dundas BI profile, click the Script Token button.

Enter a Caption.

The script language used for tokens is DundasScript. Set Data Type to the type of value that will be returned by your script:

Script token options
Script token options

Most data types support more than one Display Type, which determine which filter types can display this token:

  • Single (e.g., Single Date, Single Number filters)
  • Range Full, Range Start, Range End (e.g., Calendar Range, Range Number filters)
  • Collection (e.g., Hierarchy Value, Cascading filters)

Some additional options may appear depending on what you chose above:

  • If you chose a Hierarchy data type, click the Select Hierarchy link that appears to choose which hierarchy's members you will be returning.
  • To allow your token to appear in the Token Offset dialog available as the Advanced option in filter token menus, check Allow offset support as script parameter if applicable. You can access the offset in your script as the variable offset.
  • For tokens with a date or time hierarchy data type, optionally set the Format Override to determine how the dates are displayed in filters.

Your script should include one or more return statements, returning a value of the data type selected above. When returning a full range or a collection of values, return an array or another type of list of values, instead of just a single value of your data type. For example:

DateTime[] dates = new DateTime[2];
dates[0] = new DateTime(2017, 4, 1);
dates[1] = DateTime.Today.AddDays(-1);
return dates;

Click the submit button at the bottom of the dialog to verify the script and save the token. You will not be able to change the Data Type, Display Type, or hierarchy after this step.

4. Rename or localize a token

You can specify different captions for a token to be displayed depending on the language/culture of the user who is logged in.

Locate the token in the tokens list and click the Edit action icon.

Click the Edit action icon
Click the Edit action icon

Click the caption link at the top of the edit dialog.

To rename the token for all users, change the text under Default; otherwise, click Add localized caption.

Add localized caption
Add localized caption

For a localized caption, enter the language code in the Culture field, and fill in the Caption field.

Provide the culture and caption
Provide the culture and caption

Click the submit button at the bottom of the dialog to apply the changes.

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