Creating custom tokens
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 Today, Current week, or Year to date.
All Dundas BI users with the Create Token privilege can create new tokens.
There are three types of custom tokens you can create:
|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);|
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.
Click the action icons next to existing tokens to view details, edit, or delete.
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.
From the the hierarchy filter's token menu, select 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.
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.
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.
If desired, set Format Override to display date values in a particular format in filters with this token selected.
Depending on what Display Type was chosen, select granularity and offset for the start and/or end of the range.
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.
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:
- Date (DateTime)
- Time Hierarchy (MemberValue or DateTime)
- Numeric (double, float, decimal, int, etc.)
- Hierarchy (MemberValue)
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; dates = new DateTime(2017, 4, 1); dates = 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 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.
For a localized caption, enter the language code in the Culture field, and fill in the Caption field.
Click the submit button at the bottom of the dialog to apply the changes.