Configuring Widgets in YAML

To add widgets to a view, use parameter keys and their values. In addition to common parameters, each widget has unique parameters described on the respective widget pages.

KPI:

• KPI List
• Indicator
• Percentage KPI

Process-based:

• Funnel chart
• Process explorer
• Sphere of processes

Tables:

• Pivot Table
• Table

Charts:

• Histogram
• Donut Chart
• Combined Bar Chart
• Strip Chart
• Line Chart
• Bar Chart

Auxiliary:

• Button
• Parameter
• Text
• Filter

Common Parameters

To create a widget, use the keys listed in the table. These keys are specified in the widgets block.

Example:

widgets:
  - key: barchart-123
    type: BAR_CHART
    apiVersion: "16"
    settings:

The API version is assigned automatically to widgets when changes are saved in the YAML editor.

When creating a widget in YAML, you can specify parameters in any order. Upon saving changes in the editor, they are sorted in the same order as in the view.

Common widget parameters:

• Color
• Sorting
• Predefined Filters
• Legend
• Display Condition

Color

To define the background color of a view or widget, use the color key.

color:
  mode: VALUE

The following values are available for the mode key:

• DISABLED — disabled
• AUTO — auto
• BASE — solid
• GRADIENT — gradient
• FORMULA — custom
• RULE — by rule
• VALUES — by values

Examples of using the color key are provided below.

Solid Fill

To set a solid color for a widget or view background, use the mode key with the value BASE. Example:

color:
  mode: BASE
  value: "#000000"

The value key is used only with the Solid color mode. The value must be a HEX color code.

Gradient Fill

To apply a gradient to a widget, use the mode key with the value GRADIENT. Example:

color:
  mode: GRADIENT
  startValue: "#D6D6D6"
  endValue: "#292929"
  classCount: 5

The startValue key specifies the HEX code of the first color in the gradient, and endValue specifies the second. The classCount key accepts values from 3 to 10 and determines the number of gradient shades.

Formula-Based Coloring

Formulas can be used with three color configuration modes:

• Custom
• By rule
• By values

To configure color using a formula, use the mode key with the value FORMULA. Example:

color:
  mode: FORMULA
  formula: "'#D6D6D6'"

For the By Rule (RULE) mode, specify the rule in the formula key:

color:
  mode: RULE
  formula: 'link: "Common"."Rule 1"'

The rule name must follow the format: link: "Group Name Where Rule Is Defined"."Rule Name".

For the By Values color mode, use the items array to list required values. Within each item, you can use the Solid or By Rule color modes.

color:
  mode: VALUES
  items:
    - value: Value 1
      color:
        mode: BASE
        value: "#000000"
    - value: Value 2
      color:
        mode: RULE
        formula: 'link: "Rule 2"'

Sorting

Sorting defines the display order of values in widgets—for example, alphabetically or by indicator.

To define sorting, use the sorting key. The following keys are available:

• name — sorting name. By default, it uses the dimension name or formula used for sorting
• value — sorting value, which includes:
  
  • mode — sorting mode. Options: FORMULA or IN_WIDGET
  • formula — formula used
  • group — name of the group (key) from which the indicator is taken (only for IN_WIDGET mode)
  • index — indicator index (position in the list, starting from 0, only for IN_WIDGET mode)
• direction — sort order: ascending (ASC) or descending (DESC)

Examples of using the sorting key are provided below.

Sorting Table Column Values

sorting:
  - name: Tickets
    value:
      mode: IN_WIDGET
      group: dimensionsAndMeasures
      index: 0
    direction: DESC

Sorting a Table by Formula Using the sum Function

sorting:
  - name: sum("table"."column")
    value:
      mode: FORMULA
      formula: sum("table"."column")
    direction: DESC

Predefined Filters

Predefined filters can be applied to widgets. The filters block uses the following keys:

• name — filter name
• formula — formula used
• dbDataType — formula data type
• format — format
• filteringMethod — filtering method
• checkedValues — selected values
• formValues — for manually entered values (specified in the numberRange block)

Example of predefined filters:

filters:
  - name: case_id
    formula: '"case_table"."case_id"'
    dbDataType: STRING
    format: STRING
    filteringMethod: INCLUDE
    checkedValues: 
      - 'Value_1'
      - 'Value_2'
      - 'Value_3'
    formValues: {}
  - name: duration
    formula: '"hist_all"."duration"'
    dbDataType: INTEGER
    format: NUMBER
    filteringMethod: IN_RANGE
    checkedValues: []
    formValues:
      numberRange:
        - 0
        - 100
  - formula: '"hist_all"."duration"'

Formula Data Type

Formulas support various data types. The following values are used with the dbDataType key:

• DATE — date
• DATETIME — date and time
• DATETIME64 — date and time with subsecond precision
• FLOAT — floating-point numbers
• INTEGER — integers
• STRING — strings
• OTHER — other

Format

The following values are used with the format key:

• DATE — date
• NUMBER — number
• MONTH — month
• DATETIME — date and time
• STRING — string
• DAY_OF_WEEK — day of week
• DURATION — duration
• HOUR — hour
• MONTH_YEAR — month and year
• YEAR — year
• QUARTER — quarter
• QUARTER_YEAR — quarter and year
• DAY_OF_MONTH — day of month
• WEEK — week

Filtering Method

The following values are used with the filteringMethod key:

• INCLUDE — included
• EXCLUDE — excluded
• EQUAL_TO — equal to
• NOT_EQUAL_TO — not equal to
• STARTS_WITH — starts with
• ENDS_WITH — ends with
• CONTAINS — contains
• NOT_CONTAINS — does not contain
• EMPTY — empty values
• NONEMPTY — non-empty values
• IN_RANGE — in the range
• NOT_IN_RANGE — not in range
• GREATER_THAN — greater than
• LESS_THAN — less than
• GREATER_THAN_OR_EQUAL_TO — greater than or equal to
• LESS_THAN_OR_EQUAL_TO — less than or equal to
• LAST_TIME — last time

Selected Values

The checkedValues key adds or excludes multiple values in a filter. You must first specify the filtering method: INCLUDE or EXCLUDE. Example:

filters:
  - name: Employee
    formula: '"event_log"."responsible"'
    dbDataType: STRING
    format: STRING
    filteringMethod: INCLUDE
    checkedValues:
      - "Employee #0008"
      - "Employee #0031"
      - "Employee #0038"
    formValues: {}

Manually Entered Values

The formValues key applies custom values to a filter. The following fields and types are available:

• date: string
• dateRange: [string, string]
• duration: string
• number: number
• numberRange: [number, number]
• string: string
• lastTimeValue: number
• lastTimeUnit: enum

Each field used with this key is optional. The key can be used with all filtering methods except INCLUDE, EXCLUDE, EMPTY, and NONEMPTY.

Example usage:

filters:
  - name: Duration
    formula: '"event_log"."prev_duration"'
    dbDataType: INTEGER
    format: NUMBER
    filteringMethod: IN_RANGE
    checkedValues: []
    formValues:
      numberRange:
        - 0
        - 100

Legend

The legend displays symbols and explanations used in a widget—for example, on a chart.

To enable a legend in a widget, use the legend key.

Legend Display in Widget

To set the legend position, use the position key. The following values are available:

• NONE — disabled
• LEFT — left
• RIGHT — right
• TOP — top
• BOTTOM — bottom

Example of legend display:

legend:
  position: LEFT

Alignment

To align the legend within the widget, use the align key. Available values depend on the position:

• For LEFT and RIGHT positions:
  
  • TOP — top
  • CENTER — center
  • BOTTOM — bottom
• For TOP and BOTTOM positions:
  
  • LEFT — left
  • CENTER — center
  • RIGHT — right

Example of alignment:

legend:
  position: TOP
  align: LEFT

Width

To set the legend width, use the width key with the following structure:

• mode — display mode
  
  • FIXED — fixed (in pixels)
  • PERCENT — percentage

Example of automatic width:

legend:
  position: LEFT
  align: TOP
  width:
    mode: FIXED

Example of percentage-based width:

legend:
  position: LEFT
  align: TOP
  width:
    mode: PERCENT
    value: 20

Measure in Description

To add a measure to a widget description, use the markdownMeasures key. The following keys are available:

Local Indicator Display Condition

To define a display condition for a local indicator, use the displayCondition block.