Custom Tokens

The Dashboard widget supports the use of custom tokens in its configuration. Based on defined criteria, custom tokens resolve dynamically each time the widget is rendered.

Use Cases

• Set threshold values in a Bullet or Dial chart.
• Retrieve an image from a source URL.

Create a Custom Token

To create a custom token, add key-value pairs to the customTokens property in the Dashboard configuration object. You can use basic syntax or expanded syntax.

Basic Syntax

In basic syntax, provide key-value pairs using the following syntax:

"customTokens": {
  "key1": "value1",
  "key2": "value2"
}

For example:

"customTokens": {
  "numericKey": 42.6,
  "dateTimeKey": "2023-08-14 10:12:32",
  "textKey": "some Text"
}

The tokens display in Qrvey Composer in the following format:

{{customTokens.key}}

Continuing the example above, the tokens display as follows:

{{customTokens.numericKey}}

{{customTokens.dateTimeKey}}

{{customTokens.textKey}}

Expanded Syntax

The expanded syntax supports grouping and custom labels. In expanded syntax, use the following attributes:

• key - Name of the token.
• label - Label displayed in the token suggestion box.
• value - Value assigned to the token.

Use the following syntax to add a group of custom tokens:

"customTokens": {
  "tokenGroupLabel": [{
    "key": "token 1 key",
    "label": "token 1 label",
    "value": "token 1 value"
    },{
    "key": "token 2 key",
    "label": "token 2 label",
    "value": "token 2 value"
    }
  ]
}

For example:

"customTokens": {
  "customGroup": [{
      "key": "someNumber",
      "label": "some Number",
      "value": 42.6
      },{
      "key": "someDateTime",
      "label": "some {{DateTime}}",
      "value": "2023-08-14 10:12:32"    
      },{
      "key": "someText",
      "label": "some . Text",
      "value": "This is a sample text"
      }
    ]
}

Qrvey Composer displays the tokens in the following format:

{{customTokens.tokenGroupLabel.key}}

Based on the example configuration, Qrvey Composer displays the following individual tokens:

{{customTokens.customGroup.someNumber}}

{{customTokens.customGroup.someDateTime}}

{{customTokens.customGroup.someText}}

Apply a Custom Token to a Chart

After the customTokens property is added to the Dashboard's configuration object, the tokens are available for use in any chart. The following example shows how to add a threshold to a Bullet chart:

1. Open the embedded Dashboard widget and create or edit a dashboard.

2. Open Chart Builder to add a Bullet chart.

3. Expand the Thresholds section and select Add Threshold.

4. Select Fixed.

   

5. Set a Color, Label, and Operator in the fields provided.

6. In the Value field, enter {{ to display a list of available tokens.

7. Type the name of the custom token until it displays in the suggestion box.

8. Select the custom token.