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 data source, a predefined set, a time offset, or script.

Built-in token options include All and Null, and various relative time tokens shown for date/time and calendar filters 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

The various types of custom tokens you can create are:

Token CategoryDescriptionExample
Data Defined by querying the raw data behind a data source First day, Largest order
Named Set Defined on a specific dimension hierarchy USA, Canada, Paris
Relative Time Defined on time based parameter Current week, Last 30 days, Beginning of today
Script 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 data, relative time, or script 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. Data tokens

In the tokens list found in your Dundas BI profile, click the Data Token button to create a new data token.

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

Add a caption
Add a caption

Select a column or element from a data source or cube as the Data Element for this token, then choose a Data Category for determining which value to use.

Select the data Element and Category
Select the data Element and Category

Click Submit.

The token will appear on filters that use the same data type as the data behind the element you chose.

Using the Data token
Using the Data token

Note
If you choose a hierarchy from a data cube as your element, the token's data type is String and can only appear for string parameter types rather than hierarchy parameters.

3.2. 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 so you can easily re-select these values.

Using the Named Set token
Using the Named Set token

3.3. 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.4. 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, the following script returns a range from April 1, 2017 to today, where the end date is exclusive:

DateTime[] dates = new DateTime[2];
dates[0] = new DateTime(2017, 4, 1);
dates[1] = DateTime.Today;
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 rename a token, or specify different captions for a token to be displayed depending on the current language/culture of your user account.

First locate the token in the tokens list, select it and click the Edit icon.

Click Edit on the toolbar
Click Edit on the toolbar

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

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

Add localized caption
Add localized caption

For a localized caption, enter the IETF language tag 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.
400-15 Gervais Drive
Toronto, ON, Canada
M3C 1Y8

North America: 1.800.463.1492
International: 1.416.467.5100

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