Chart On-screen Settings

Parameters of measures, dimensions, columns and analyzed objects can be defined as on-screen settings, bringing the settings easily available in the dashboard (above the chart). When the commonly used settings are defined as the on-screen settings, the settings dialog doesn't need to be opened at all.

The on-screen settings can be standard which define that an existing measure/dimension/column parameter is shown as the on-screen setting. For the standard on-screen settings, it's enough to specify which parameter is shown.

The on-screen settings can also be custom, meaning that the setting is defined from the scratch, i.e., which type of UI control etc. The custom on-screen settings itself don't have any behavior, until they have been bound to chart settings using the linked settings.

Common Parameters

Following parameters used for all types of on-screen settings:

• parameter (string): Technical name of the setting. For standard on-screen settings, the name appearing in the chart configuration (JSON) should be used. For custom on-screen settings, this field is used to identify the on-screen setting in the linked settings (it's optional and can be freely defined).
• label (string): Visible label text for the field.
• maxWidth (integer): Maximum width of the field in pixels. This setting is useful, if you want to have more space for specific settings.
• newLine (boolean): Defines whether the setting is positioned to a new line. When defining in multiple lines, the on-screen settings will take more screen space.

Dropdown Lists Common Parameters

All dropdown list UI controls support the following parameters:

• exclude (string array): List of values that are hidden from the dropdown list showing model entities (such as case/event attribute names or values).
• excludeIds (integer array): List of object IDs that are hidden from the dropdown list. Applicable only when the list shows database stored objects that have an ID (such as models, datatables, scripts, etc.).
• excludeCaseIdColumn (boolean): When showing case or event attribute, this setting will hide the case id column from the list. Use value true to hide the case id.
• includeChartFilters (boolean): With a dropdown list showing model data, this setting determines whether the list content is filtered with the chart filter rules. For example, the shown case attribute values may be filtered with the chart filters, or the chart filters can be ignored.
• includeOnly (string array): This setting filters the shown dropdown list values by explicitly specifying the shown values.
• includeOnlyIds (integer array): This setting filters the shown dropdown list by explicitly specifying the object IDs that should be shown. Applicable only when the list shows database stored objects that have an ID.
• allowedDatatypes (string array): This setting filters shown case and event attributes in the dropdown list by explicitly specifying the attribute datatypes which are shown. Allowed values: String, Integer, Float, DateTime, and Boolean.
• showStatistics (boolean): When the value is true, the dropdown list for model objects (such as case/event attributes, event types, variations, flows, etc.) shows also statistical data for the objects, such as counts and percentages. This setting is optional, and if not defined, the model's Show Object Count Statistics model setting is used.

Standard On-screen Settings Parameters

On-screen settings are standard when the type parameter is defined. Standard on-screen settings support following parameters:

• type: Either measure, dimension, eventtypemeasure (for Event measures in flowchart), flowmeasure (for Flow measures in flowchart) or root. If slicing into dimensions is disabled, columns correspond to dimensions. When this parameter is defined, the on-screen setting is standard, and when not defined, it's custom (see below).
• index (integer): Zero-based index number of the expression. Not used for the root.

Custom On-screen Settings Parameters

In addition to the measure/dimension/column parameters, it's also possible to define custom on-screen settings, i.e,. settings that are not based on any existing chart setting. For example, when using custom expressions, it's possible to define parameters for them as on-screen settings. To do that, there are additional properties to be set that define which kind of UI control is used.

The following parameters can be used for custom on-screen settings:

• control (string): UI control type which is one of the following: singleselectlist, dynamicsingleselectlist, multiselectlist, singlelinetext, multilinetext, numericfield, datefield, datetimefield, checkbox, colorpicker, bpmneditor. This parameter is mandatory for custom on-screen settings, and if it's not defined in the on-screen settings json, the changes cannot be applied.
• mandatory (boolean): Defined that the field is mandatory. If a mandatory field is missing, the chart shows a message about a missing value.
• value (string): Current value of the on-screen setting. Defined using the stringified value format which is the same format as the dashboard variables are stored.
• updateImmediately (boolean): Specifies whether the chart is updated right away when the value is being changed. When disabled, the value updated only when cursor leaves the input box or the dropdown list is closed. Applicable only for the controls singlelinetext and multiselectlist.

It's possible to override the UI control settings for the standard on-screen settings. All above mentioned parameters can be used, except the the UI control type cannot be changed (i.e. the control parameter cannot be used).

Numeric Fields

Numeric fields (control=numericfield) support the following parameters:

• minValue (number): Specifies the minimum allowed numerical value that can be inputed to the numerid field.
• minValue (number): Specifies the maximum allowed numerical value that can be inputed to the numerid field.
• decimals (integer): Specifies whether decimal numbers can be specified (or only integer numbers).
• unit (string): Specified unit is shown next to the numerical value.

Dynamic Dropdown Lists

Dynamic dropdown lists (control=dynamicsingleselectlist or multiselectlist) support the following parameters:

• dynamicType (string): Defines type of items shown by the dropdown list. One of the following: CaseAttributes, CaseAttributeValues, EventAttributeValues, EventAttributes, EventTypes, Variations, FlowsStartingFrom, StartEventTypes, EndEventTypes, CaseIds, DataTables, DataTableColumns, DataTableColumnsByDatatableName, AnalysisColumns, DataTablesOfProject, Models, ModelById, Projects, Scripts.
• attributeName (string): Specifies the name of the case or event attribute whose values are displayed in the dropdown list. This is used for static selection when dynamicType is set to CaseAttributeValues or EventAttributeValues. If this parameter is required but not defined, the value of the previous on-screen setting is used if that on-screen setting dynamicType is CaseAttributes (for CaseAttributeValues) or EventAttributes (for EventAttributeValues).
• eventTypeName (string): Event type name. Used when dynamicType is FlowsStartingFrom. If this parameter is required but not defined, the value of the previous on-screen setting is used if that on-screen setting dynamicType is EventTypes.
• includeNullSelection (boolean): When true, an item is added as first in the list, representing the null value.

Static Dropdown Lists

Static dropdown lists (control=singleselectlist) supports the following parameters:

• options: List of options the dropdown list. Specified as an array of object with following properties:
  • label (string): User visible text in the dropdown list.
  • identifier (string): Actual stored value to the parameter.
• optionsData (string): Defines type of items shown by the dropdown list. One of the following: AggregateNumbers, AggregateDates, AggregateDurations, AggregateDurationsWithoutNulls, AggregateText, SqlAggregateNumbers, SqlAggregateDates, SqlAggregateText, TimeUnits, DurationUnits, Periods, CountOrPercentage, CountOrPercentageCases, CountOrPercentageEvents, NumericalComparison, EventIndex, FlowStartEndEvent, DataTypes.

Examples

Standard on-screen setting showing the first dimension's Attribute parameter and the second dimensions Period parameter.

[
  {
    "type": "dimension",
    "index": 0,
    "parameter": "Attribute",
    "maxWidth": 500
  },
  {
    "type": "dimension",
    "index": 1,
    "parameter": "Period",
    "label": "Time"
  }
]

Creates a custom numeric field, where minimum value is 1 on decimals are allowed:

[
  {
    "type": "measure",
    "index": 0,
    "parameter": "var1",
    "maxWidth": 200,
    "control": "numericfield",
    "decimals": 2,
    "minValue": 1
  }
]

Multiselect dropdown list where a case attribute (region) can be selected.

[
	{
		"label": "Select regions",
		"control": "multiselectlist",
		"dynamicType": "CaseAttributeValues",
		"parameter": "region",
		"attributeName": "Region",
		"value": "[\"0Austin\", \"0Dallas\", \"0New York\"]"
	}
]

Single-select list for a case attribute, and a multi-select list for the case attribute values. The lists are bound together, so the second list contains values for the case attribute selected in the first list. The includeChartFilters parameter prevents the chart's filters from affecting the counts and available items of these lists.

[
	{
		"label": "Select attribute",
		"control": "dynamicsingleselectlist",
		"dynamicType": "CaseAttributes",
		"value": "0Customer Group",
		"includeChartFilters": false
	},
	{
		"label": "Select values",
		"control": "multiselectlist",
		"dynamicType": "CaseAttributeValues",
		"includeChartFilters": false,
		"value": "[\"0Men\", \"0Women\"]"
	}
]

Single-select list containing the predefined options:

[
  {
    "maxWidth": 200,
    "label": "Choose fruit",
    "control": "singleselectlist",
    "options": [
     {
       "label": "Apples",
       "identifier": "apples"
     },
     {
       "label": "Oranges",
       "identifier": "oranges"
     },
     {
       "label": "Bananas",
       "identifier": "bananas"
      }
    ]
  }
]