Creating custom tokens
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 Today, Current week, or Year to date.
All users with the Create Token privilege can create new tokens.
The various types of custom tokens you can create are:
| Token Category | Description | Example |
|---|---|---|
| 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 the main 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. Data tokens
In the tokens list found in your profile, click the Data Token button to create a new data token.
In the New Data Token dialog, enter a Caption for the token.
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.
Click Submit.
The token will appear on filters that use the same data type as the data behind the element you chose.
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.
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 so you can easily re-select these values.
3.3. Relative Time token
In the tokens list found in your 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.4. Script token
In the tokens list found in your 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.)
- String
- 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, 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 the caption link at the top of the edit dialog.
To rename the token, change the text under Default; otherwise, click Add localized caption.
For a localized caption, enter the IETF language tag in the Culture field, and fill in the Caption field.
Click the submit button at the bottom of the dialog to apply the changes.