# Celonis Product Documentation

##### Chart
###### Introduction to Charts

With the chart widget, you can combine visuals like bars, lines, areas, and points to represent your data.

###### Chart Types

A list of minimalistic configuration examples.

###### Bar Chart

YAML configuration

id: cashflow2-new
type: chart
settings:
name: Cash
showLegend: true
encodings:
x:
field: CASHFLOW_EVENTTIME_TS
format: Q%q
type: ordinal
visuals:
- mark:
type: bar
encodings:
y:
field: PAYROLL_TS


###### Line Chart

YAML configuration

id: DSO_Chart
type: chart
settings:
name: Days Sales Outstanding
showLegend: true
encodings:
x:
field: ENTRY_QUARTER
type: ordinal
format: Q%q '%y
visuals:
- mark:
type: line
point: true
encodings:
y:
field: KPI_DAYS_SALES_OUTSTANDING_TITLE


###### Area Chart

YAML configuration

id: revenue-chart
type: chart
settings:
name: Cash
showLegend: true
sortBy:
- field: CASHFLOW_EVENTTIME_TS
encodings:
x:
field: CASHFLOW_EVENTTIME_TS
format: Q%q
type: ordinal
visuals:
- mark:
type: area
encodings:
y:
field: PAYROLL_TS
- mark:
type: area
encodings:
y:
field: DEBT_TS
axis:
title: " "


###### Scatter Plot

The scatter plot can display two dimensions on x-axis, y-axis and a third dimension via the color encoding.

Using a size encoding it is also possible to make a bubble plot.

YAML configuration

id: riskScatterplot
type: chart
settings:
encodings:
x:
field: LIKELIHOOD
type: quantitative
zeroBased: false
y:
field: IMPACT
type: quantitative
zeroBased: false
color:
field: RISKCOLOR
scheme: DIVERGING_GREEN_TO_YELLOW_TO_RED
thresholds:
- 30
- 150
visuals:
- mark:
type: point
point:
shape: circle
width: 10
- mark:
type: text
encodings:
text: IMPACT


###### Lollipop Chart

YAML configuration

id: Lollipop
type: chart
settings:
name: Lollipop
encodings:
x:
field: EVENTTIME
type: ordinal
format: "%H:%m"
y:
field: COUNT_ACTIVITIES
title: Value1
visuals:
- mark: lollipop
- mark:
type: point
point:
width: 10
- mark:
type: point
point:
width: 10
encodings:
y:
field: TOTAL_NUMBER_OF_INVOICES
title: Value2


###### Stacked Charts

Stacked by dimensions:

YAML configuration

id: CHART_COSTS
type: chart
settings:
name: Costs
showLegend: true
encodings:
x:
field: EXPENSES_EVENTTIME_TS
type: ordinal
format: Q%q
color:
field: EXPENSES_TYPE
scheme: DIVERGING_BLUE_TO_PINK
visuals:
- mark:
type: bar
encodings:
y:
field: EXPENSES_USD_TS
stackBy: EXPENSES_TYPE



Stacking multiple KPIs:

YAML configuration

id: ACV-Gap-chart
type: chart
settings:
name: Revenue Gap
showLegend: true
encodings:
x:
field: CLOSEDATE_MONTH
type: ordinal
visuals:
- mark: bar
encodings:
y:
stack:
- GEN_pipe_to_be_closed
- WIN_RATE
- QUOTA
legend: true


###### Grouped Bar Chart

Grouping by dimension:

YAML configuration

id: groupedChart
type: chart
settings:
name: Grouped by (dimension) Material Class x-axis per month
showLegend: true
encodings:
x:
field: MATERIAL_DATE_QUARTER
type: ordinal
axis:
title: Material Class
format: "%y/%m"
color:
field: MATERIAL_CLASS
scheme: CATEGORICAL
visuals:
- mark:
type: bar
encodings:
y:
field: COUNT_TABLE__STACKINGSAMPLE_WITHOUT_TARGETS
groupBy: MATERIAL_CLASS



Grouped KPIs:

YAML configuration

id: groupedStackedChart
type: chart
settings:
name: Grouped - Stacked bar chart per Quarter (stacked KPIs)
encodings:
x:
field: TIMEQUARTER
type: ordinal
format: Q%q
visuals:
- mark: bar
encodings:
y:
stack:
- - WON
- COMMIT
- - COMMIT_RISK
- BEST_CASE
- PIPELINE


###### Horizontal Charts

YAML configuration

id: horizontalGroupedChart
type: chart
settings:
name: Grouped by (dimension) Material Class x-axis per month
showLegend: true
encodings:
x:
field: MATERIAL_DATE_QUARTER
type: ordinal
axis:
title: Material Class
format: "%y/%m"
color:
field: MATERIAL_CLASS
scheme: CATEGORICAL
visuals:
- mark:
type: bar
orientation: horizontal
encodings:
y:
field: COUNT_TABLE__STACKINGSAMPLE_WITHOUT_TARGETS
groupBy: MATERIAL_CLASS


###### Configuring Charts

By making small changes in the YAML configuration, you can control the visual configuration of the charts.

###### Choose visuals

You can select one or more visuals to be shown on your chart:

YAML configuration

id: kpi_chart
type: chart
settings:
encodings:
x:
field: ENTRY_QUARTER
type: ordinal
format: Q%q
visuals:
- mark:
type: bar
point: true
legend: Invoice Volume '20
encodings:
y:
field: KPI_TOTAL_INVOICE_VALUE
format: $.2s axis: title: Invoice Volume position: left  YAML configuration id: kpi_chart type: chart settings: encodings: x: field: ENTRY_QUARTER type: ordinal format: Q%q visuals: - mark: type: bar point: true legend: Invoice Volume '20 encodings: y: field: KPI_TOTAL_INVOICE_VALUE format:$.2s
axis:
title: Invoice Volume
position: left
- mark:
type: line
point: true
encodings:
y:
field: KPI_DAYS_DELINQUENT_2020
units: " d"
axis:
title: " "
position: right



YAML configuration

id: kpi_chart
type: chart
settings:
encodings:
x:
field: ENTRY_QUARTER
type: ordinal
format: Q%q
visuals:
- mark:
type: bar
point: true
legend: Invoice Volume '20
encodings:
y:
field: KPI_TOTAL_INVOICE_VALUE
format: $.2s axis: title: Invoice Volume position: left - mark: type: line point: true legend: ADD '20 encodings: y: field: KPI_DAYS_DELINQUENT_2020 units: " d" axis: title: " " position: right - mark: type: line point: shape: rect width: 40 legend: ADD '19 encodings: y: field: KPI_DAYS_DELINQUENT_2019 units: " d" axis: title: Average Days Delinquent position: right  ###### Sort or order the content You can sort the content along the x-axis. Sorted by Material Class YAML configuration id: sortedChart type: chart settings: sortBy: - field: MATERIAL_CLASS direction: ASC visuals: - mark: type: bar encodings: y: field: COUNT_TABLE__STACKINGSAMPLE - mark: type: line encodings: y: field: COUNT_TABLE__STACKINGSAMPLE_two encodings: x: field: MATERIAL_CLASS  Sorted by Count YAML configuration id: sortedChart type: chart settings: sortBy: - field: COUNT_TABLE__STACKINGSAMPLE direction: ASC visuals: - mark: type: bar encodings: y: field: COUNT_TABLE__STACKINGSAMPLE encodings: x: field: MATERIAL_CLASS  ###### Add axis description and legends The legend is added in the chart settings. YAML configuration id: myChart settings: showLegend: true  The axis position (left, right) and the axis title are set in the encodings.  - mark: encodings: y: axis: title: "My axis title" position: right ###### Change the color There are three ways how you can apply colors in a chart: 1. You can apply predefined color schemes in the chart settings. These colors will be applied to the different visuals (for a list of available color schemes see "What are the available Color Schemes that I can use?" in FAQ) 2. You can use a predefined color scheme to encode a certain data attribute with color in an encodings configuration (see "Properties specific to Color Encoding" in FAQ). 3. You can directly apply a specific color to the marks of one visual (see "What are the configuration properties of mark?" in FAQ) YAML configuration id: myChart settings: colors: SEQUENTIAL_BLUE  ###### Define chart interactions The chart interactions can be defined in the chart settings. ###### Tooltip Tooltips are enabled by default. They can be disabled in the chart settings. YAML configuration id: myChart settings: interactions: tooltip: false  Use the detail encoding to add more fields to be shown in the Tooltip in addition to the data that is visually shown in the chart. View YAML id: ganttChart type: chart settings: name: Gantt Chart v1 interactions: selection: true tooltip: true sortBy: - field: GANTT_ACTIVITIES.START visuals: - mark: type: rect orientation: none encodings: x: field: GANTT_ACTIVITIES.START format: "%d.%m.%y" title: Time x2: GANTT_ACTIVITIES.END color: GANTT_ACTIVITIES.ACTIVITY y: GANTT_ACTIVITIES.ACTIVITY detail: - field: GANTT_ACTIVITIES.milestone - field: GANTT_ACTIVITIES.START title: Custom Start Title format: "%d.%m.%y" ###### Selections Selections are enabled by default. They can be disabled in the chart settings. YAML configuration id: myChart settings: interactions: selection: true  ###### Target lines If one of the chart's encodings is a kpi that has a target, a target line is shown by default on the point where the kpi target marks. Assuming one of the kpis has a defined target (KPI targets can be set on KPI lists or KPI Bowlers) the following yaml will show a target line: YAML configuration settings: encodings: x: field: KPI y: field: KPI2  On the other side, if this target line needs to be hidden, it can be done by: YAML configuration settings: encodings: x: field: KPI kpiTargets: false y: field: KPI2  Target lines are dashed and grey by default. This can't be customized via yaml. ###### Position lines Position lines can be defined on each data point of the field accessor Shorthanded to use the top level encoding: YAML configuration settings: encodings: x: field: KPI y: field: KPI2 visuals: - mark: rule  Visual encoding specific: YAML configuration settings: encodings: x: field: KPI y: field: KPI2 visuals: - mark: type: rule encodings: x: field: KPI3  Position lines can be defined on a KPI that resolves to one data value (datum) Use datum to resolve a single value from a KPI. (as opposed to field which queries a KPI value for every data point) YAML configuration settings: encodings: x: field: KPI y: field: KPI2 visuals: - mark: type: rule encodings: x: datum: KPI3  Position lines can be defined with a constant value Use value to manually define where the position line appears on the axis. YAML configuration settings: encodings: x: field: KPI y: field: KPI2 visuals: - mark: type: rule encodings: x: value: 30  All position lines are blue and dashed by default. Nevertheless, this can be customized via yaml configuration. ### Using custom domains and zeroBased with Position Lines It is suggested to always define custom domains and zeroBased properties in chart level encodings. Defining these properties in visual level encodings might cause unexpected behavior. Defining domains and zeroBased properties in mark rule encodings will have no effect. See the example on the right. YAML configuration encodings: y: field: COUNT_TABLE__STACKINGSAMPLE domain: - 4 - 20 zeroBased: false x: field: MATERIAL_CLASS visuals: - mark: line - mark: type: rule labels: true style: dashed color: RED encodings: y: datum: KPI_X title: Average ###### FAQ (Frequently Asked Questions) ###### What are visuals, marks and encodings? The main parts of every chart configuration are its visuals. Visuals define visualization layers of the chart that contain mainly two parts: mark and encodings. • the visual mark defines the type of graphical object (such as bar, line, area, point) that is used to represent data items (eg. invoices) • and encodings allow to define how data attributes (eg. customer name, due date, value) of these data items are mapped to specific visual properties (such as color, x-position, y-position) For example: If you want to create simple charts that only contain one type of mark such as a bar chart, you specify one visual with mark: bar and encodings for x and y. Simple Bar Chart YAML configuration id: cashflow2-new type: chart settings: name: Cash showLegend: true visuals: - mark: bar encodings: y: PAYROLL_TS x: field: CASHFLOW_EVENTTIME_TS format: Q%q type: ordinal For a combination of multiple graphical objects in one chart such as bars and lines, or lines and points, you can layer multiple visuals with each of them defining a different mark.This way, you can create more complex charts such as a bar+line chart. Bar + Line Chart YAML configuration id: kpi_chart type: chart settings: encodings: x: field: ENTRY_QUARTER type: ordinal format: Q%q visuals: - mark: bar legend: Invoice Volume '20 encodings: y: field: KPI_TOTAL_INVOICE_VALUE format:$.2s
axis:
title: Invoice Volume
position: left
- mark:
type: line
point: true
encodings:
y:
field: KPI_DAYS_DELINQUENT_2020
units: " d"
axis:
title: " "
position: right


###### Where can I specify encodings?

Encodings can be specified in two places:

1. in visuals. Every visual needs at least encodings for x and y positions to know what data attributes should define the spatial layout of the visual.

2. as a direct property of settings. This can be helpful if you have multiple visuals in one chart which all use the same x-axis. In this case, you can save some writing effort by defining the common x encoding at this root level. The encodings specified at this root level will be used by all visuals that do not specify a respective encoding of their own.

For example, the following two yaml configurations produce this same chart:

Bar + Line Chart

Repeating the definition of x encoding for every visual in the visuals array:

YAML configuration

id: kpi_chart
type: chart
settings:
visuals:
- mark: bar
legend: Invoice Volume '20
encodings:
y:
field: KPI_TOTAL_INVOICE_VALUE
format: $.2s axis: title: Invoice Volume position: left x: field: ENTRY_QUARTER type: ordinal format: Q%q - mark: type: line point: true legend: ADD '20 encodings: y: field: KPI_DAYS_DELINQUENT_2020 units: " d" axis: title: " " position: right x: field: ENTRY_QUARTER type: ordinal format: Q%q  Defining the x encoding once at the root level so it can be used by every visual in the visuals array: YAML configuration id: kpi_chart type: chart settings: encodings: x: field: ENTRY_QUARTER type: ordinal format: Q%q visuals: - mark: bar legend: Invoice Volume '20 encodings: y: field: KPI_TOTAL_INVOICE_VALUE format:$.2s
axis:
title: Invoice Volume
position: left
- mark:
type: line
point: true
encodings:
y:
field: KPI_DAYS_DELINQUENT_2020
units: " d"
axis:
title: " "
position: right


###### What are the configuration properties of encodings?

Encoding is an object that can contain sub-objects x, y, color, text. These sub-objects can then contain the following properties:

Property

Type

Description

field

<KnowledgeModel AttributeId>

Required.A string reference to an attribute in the connected knowledge model from which to pull the data.

type

"nominal" | "ordinal" | "quantitative" | "temporal"

The type of measurement for the encoded field.

Default: the default value of type is based on the primitive data type of the encoded field:

• quantitative for number values

• temporal for date values

• nominal for string values (use for categorical values)

• ordinal (is not used by default as it is not possible to automatically derive whether the data has a natural order)

As the type property describes the semantics of the data rather than the primitive data type, the defaults are only an educated guess.

For example, although zip codes are numbers, their measurement type should be nominal as they represent categorical IDs rather than quantitative measures.

In such cases, it is advisable to manually set the type property.

title

String

The title of the encoding is used in the tooltip, in the legend, and as the axis title.

Default: the default value of title is the displayName of the encoded field/attribute from the Knowledge Model.

format

String

The format property takes a format specifier string as available in d3-format (for number formatting) and d3-time-format (for date formatting).

units

String

The units will be added postfix to every formatted data value.

Default: the default value of units is the unit property of the encoded field/attribute from the Knowledge Model.

domain

Array

The domain property can be used to specify a custom domain for the encoding.

Default: the default domain will automatically be calculated from the values in the encoded data field.

### Note

This property can be overridden if used in visual level encoding by another visual so it's suggested to set this property in top(chart) level encoding

Examples:

• for a quantitative y-position encoding with percentage values, you may specify a domain of [0, 1] to make sure that the y-axis always spans the values from 0 to 100%.

• for a categorical x-position encoding with country names, you can specify the following domain to fix all values that should be shown on the axis: ["Germany", "Kenia", "Brazil", "India", "New Zealand", "Canada"]

kpiParams

Properties specific to X and Y encodings:

axis

AxisSpec

An axis specification object:

Property

Type

Description

position

"top" | "right" | "bottom" | "left"

Where to place the axis of this position encoding.

Default:

• for x encodings: "bottom"

• for y encodings: "left"

title

String

The title is to be shown on the axis.

Default: the default value of axis.title is the title of the encoding.

hide

true | false

Specify true to hide the axis.

Default: false.

ticks

Number

tickOverlap

grid

true | false

Specify false to hide the gridline.

Default: true.

stackBy

<KnowledgeModel AttributeId>

A string reference to an attribute in the connected knowledge model that is used to split a bar or area into multiple stacked parts.

Note: currently only supported in combination with mark: bar or mark: area

groupBy

<KnowledgeModel AttributeId>

A string reference to an attribute in the connected knowledge model that is used to create grouped bars.

Note: currently only supported in combination with mark: bar

stack

Array of <KnowledgeModel AttributeId>

zeroBased

true | false

Default: true.

Note: This property can be overridden if used in visual level encoding by another visual so it's suggested to set this property in top(chart) level encoding

kpiTargets

true | false

Whether to show kpi target lines

Default: true.

Properties specific to X and Y encodings within visuals

datum

<KnowledgeModel KpiId>

A string reference to a kpi in the connected knowledge model that resolves to a constant value.

Note: As opposed to field, the datum kpi is not queried with the other fields but queried independently. This is useful for position lines

value

String | Number | boolean | Date

Constant value to be used to map to a visual value.

Properties specific to Color Encoding:

scheme

ColorScheme

A string reference to a color scheme. Color schemes usually start with one of the following prefixes: CATEGORICAL, SEQUENTIAL, or DIVERGING.For example: CATEGORICAL, SEQUENTIAL_BLUE, SEQUENTIAL_BLUE_REVERSE, DIVERGING_CYAN_TO_ORANGE.For a full list of available color schemes see "What are the available Color Schemes that I can use?" in the FAQ.

Default: the default value ofschemeis based on the type property:

• default for type quantitative, temporal, ordinal: SEQUENTIAL_BLUE

• default for type nominal: CATEGORICAL

thresholds

Number[]

kpiTargets

true | false

Toggle

###### What are the configuration properties of mark?

Property

Type

Description

type

"line" | "bar" | "point" | "area" | "text" | "lollipop" | "rect" | "rule"

Required. The mark type defines the visual marks that will be shown for data items.

Note: You can exchange "bar" for "line" to see how the same data would look like with another representation.

labels

true | false

Whether to show data labels.

color

ColorEnum

explicitly specify which color to use for the marks of this visual. By default the color will be assigned depending on the color scheme that you provided in the config.

Possible color enum values are:

• <HUE>_10, <HUE>_20, <HUE>_30, <HUE>_40, <HUE>_50 where <HUE> can be one of the following: BLUE, RED, GREEN, PURPLE, PINK

• WHITE, GRAY_10, GRAY_20, GRAY_30, BLACK

orientation

"vertical" | "horizontal" | "none"

The orientation defines the tooltip behavior and whether bars should be vertically or horizontally oriented.

Default: depends on the type of the visual, see the article about orientation of visuals.

Note: if you specify orientation: horizontal, make sure to use the y encoding for the categorical values and the x encoding for the numerical values.

Properties specific to type: bar

bandwidth

Number

Width of a bar in a bar chart in pixels.

Default: the default value of bandwidth is calculated such that all bars just fit into the chart without overlap (and a bit of padding in between bars).

Note: bars can never exceed the default bandwidth and thus will always fit into the chart without overlap.

Properties specific to type: rule

style

"solid" | "dashed"

The line style to be applied to the specified rules

Properties specific to type: line

point

true | false | PointSpec

Whether to show markers for every data point on the line.

Specifying true will render markers on the line with default configuration.

You can also specify a PointSpec object instead:

Property

Type

Description

width

Number

Width of the marker in pixels.

height

Number

Height of the marker in pixels.

shape

"CIRCLE" | "RECT"

Default: "CIRCLE".

Default: false.

###### What is the shortcut syntax for default configuration of encodings and marks?

For encodings and mark configurations, you can use the following shortcut syntax if you don't need to do further customizations.

This may be useful to quickly test different chart configurations with default settings.

The following two code blocks are equivalent:

mark: point
encodings:
x: RECORDID.EVENTTIME_QUARTER
y: RECORDID.PAYROLL_TS
color:
scheme: DIVERGING_CYAN_TO_ORANGE
mark:
type: point
encodings:
x:
field: RECORDID.EVENTTIME_QUARTER
y:
field: RECORDID.PAYROLL_TS
color:
scheme: DIVERGING_CYAN_TO_ORANGE:
field: BUSINESS_UNIT
###### What are the available Color Schemes that I can use?

ColorSchemes can be applied in the chart settings colors property or in the color encoding scheme property.

You use one of the following color schemes:

Color schemes

# Categorical
CATEGORICAL
CATEGORICAL_ALT_1
CATEGORICAL_ALT_2
CATEGORICAL_ALT_3

# Diverging
DIVERGING_CYAN_TO_ORANGE
DIVERGING_BLUE_TO_PINK
DIVERGING_PURPLE_TO_TEAL
DIVERGING_GREEN_TO_RED
DIVERGING_GREEN_TO_YELLOW_TO_RED
DIVERGING_ORANGE_TO_CYAN
DIVERGING_PINK_TO_BLUE
DIVERGING_TEAL_TO_PURPLE
DIVERGING_RED_TO_GREEN
DIVERGING_RED_TO_YELLOW_TO_GREEN

# Sequential
SEQUENTIAL_GRAY
SEQUENTIAL_CYAN
SEQUENTIAL_TEAL
SEQUENTIAL_BLUE
SEQUENTIAL_PURPLE
SEQUENTIAL_PINK
SEQUENTIAL_RED
SEQUENTIAL_ORANGE
SEQUENTIAL_YELLOW
SEQUENTIAL_GREEN
SEQUENTIAL_GRAY_REVERSE
SEQUENTIAL_CYAN_REVERSE
SEQUENTIAL_TEAL_REVERSE
SEQUENTIAL_BLUE_REVERSE
SEQUENTIAL_PURPLE_REVERSE
SEQUENTIAL_PINK_REVERSE
SEQUENTIAL_RED_REVERSE
SEQUENTIAL_ORANGE_REVERSE
SEQUENTIAL_YELLOW_REVERSE
SEQUENTIAL_GREEN_REVERSE