The Chart KATA widget can build complex, dynamic charts with mixed visualizations and datasets from multiple sources. The datasets and chart schema are both defined using a KATA dialect.

• Configuration
  • Datasets
    • automation:
    • dataQuery:
    • manual:
  • Chart
    • axis:
      • x:, y:, y2:
    • color:
    • data:
      • series:
      • type:
    • grid:
      • x:, y:
    • legend:
      • style:table:
    • tooltip:
• Examples
  • Timeseries: Stacked bar of tickets created this year by group
  • Timeseries: Line comparison of contact methods
  • Pie: Tickets created this year by bucket
  • Donut: Contact methods

Configuration

Datasets

A dataset is a collection of series data. An /identifier names the dataset.

Each series within a dataset has a unique key name containing an array of values.

For instance, a time-series dataset could include a series named ts with timestamps for the x-axis, and a second series named values with the y-axis values.

automation:

Load series data from a ui.chart.data automation.

This can synthesize and preprocess chart data from anywhere: third-party APIs, Cerb records, business intelligence tools, etc.

automation/avgInflow:
  uri: cerb:automation:example.chartData.avgTicketInflows
  inputs:
    date_range: today to +4 weeks
  disabled@bool: no

dataQuery:

Load data from a data query.

dataQuery/tickets:
  query@text:
    type:worklist.subtotals
    of:ticket
    by:[created@month,group]
    query:(created:"this year")
    format:${format}
  query_params:
    format: timeseries

manual:

Load static data.

manual/series0:
  data:
    x@csv: 2022-01-01,2022-02-01,2022-03-01,2022-04-01
    custom@csv: 33,66,99,500

Chart

A {{datasets.name}} placeholder is available for each defined dataset. For instance, a grid: line can be rendered from a dynamically computed value (e.g. average, threshold, goal).

data:
  type: bar
  series:
    tickets:
      name: Tickets
      x_key: ts
    series0:
      name: Custom Series
      x_key: x
      y_axis: y2
      y_type: line
    tasks:
      name: Tasks
      x_key: ts
  stacks:
    0@csv: tickets
    1@csv: tasks

axis:
  x:
    label: Time
    type: timeseries
    tick:
      date:
        format: %Y-%m
  y:
    label: Tickets/Tasks
  y2:
    label: Custom

grid:
  y:
    lines:
      0:
        value: {{datasets.baseline.value}}
        text: Target ({{datasets.baseline.value}})
        position: start

axis:

x:, y:, y2:

tick:

tick:format:

tick:format:duration:

color:

Each dataset can specify a color pattern using data:series:*:color_pattern:. Several pre-defined color patterns are available through code autocompletion.

If a pattern key ends in the _dark suffix it will be preferred in dark mode.

If a color pattern is named default it will apply to any series without an explicit color assigned.

If multiple datasets share the same non-default color pattern, colors will be synchronized for values that are identical. For instance, if two series compare groups over current/prior year, then ‘Support’ will have the same color in both datasets.

data:

series:

Each series: key is a dataset name that may contain multiple series.

type:

grid:

x:, y:

lines:

Each line must have a unique key name containing:

legend:

style:table:

tooltip:

Examples

Timeseries: Stacked bar of tickets created this year by group

Datasets:

dataQuery/tickets:
  query@text:
    type:worklist.subtotals
    of:ticket
    by.count:[created@month,group]
    query:(created:"first day of this month -1 year")
    format:timeseries

Chart:

data:
  type: bar
  series:
    tickets:
      x_key: ts
  stacks:
    0@csv: tickets

axis:
  x:
    type: timeseries
    tick:
      format: %B '%y

tooltip:
  grouped@bool: no

Timeseries: Line comparison of contact methods

Datasets:

dataQuery/calls:
  query@text:
    type:worklist.subtotals
    of:call
    by:[created@year]
    format: timeseries

dataQuery/tasks:
  query@text:
    type:worklist.subtotals
    of:task
    by:[created@year]
    format: timeseries

dataQuery/tickets:
  query@text:
    type:worklist.subtotals
    of:ticket
    by:[created@year]
    query:(status:!d)
    format: timeseries

Chart:

data:
  type: line
  series:
    tickets:
      x_key: ts
      name: Tickets
    tasks:
      x_key: ts
      name: Tasks
    calls:
      x_key: ts
      name: Calls

axis:
  x:
    type: timeseries
    tick:
      format: %Y

tooltip:
  grouped@bool: no

Pie: Tickets created this year by bucket

Datasets:

dataQuery/tickets:
  query@text:
    type:worklist.subtotals
    of:ticket
    by.count:[group_bucket]
    query:(created:"this year")
    format:pie

Chart:

data:
  type: pie
  series:
    tickets:

Donut: Contact methods

Datasets:

dataQuery/calls:
  query@text:
    type:worklist.metrics
    values.calls:(
      of:call
      function:count
      field:id
      query:()
    )
    format: pie

dataQuery/tasks:
  query@text:
    type:worklist.metrics
    values.tasks:(
      of:task
      function:count
      field:id
      query:()
    )
    format: pie

dataQuery/tickets:
  query@text:
    type:worklist.metrics
    values.tickets:(
      of:ticket
      function:count
      field:id
      query:(status:!d)
    )
    format: pie

Chart:

data:
  type: donut
  series:
    calls:
      name: # Calls
    tasks:
      name: # Tasks
    tickets:
      name: # Tickets