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.

Configuration

On-screen settings are defined as a JSON array, where each item has the following properties:

• 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): Index of the expression. Not used for the root.
• parameter (string): Name of the parameter.
• label (string): Custom label for the field.
• maxWidth (integer): Maximum width of the shown setting in pixels.
• newLine (boolean): Defines whether the setting is positioned to a new line for more spacing between settings.
• exclude (string array): List of values that are hidden from the dropdown list showing model objects.
• 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.
• 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.

Custom On-screen Settings

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.

Common settings

The following parameters can be used:

• 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 also 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).

UI control: numericfield

• 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.

UI control: dynamicsingleselectlist and multiselectlist

• 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.

UI control: singleselectlist

• options: List of options the dropdown list. Specified as an array of object with following properties:
  • label: User visible text in the dropdown list.
  • identifier: 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"
      }
    ]
  }
]