Cumul.io dashboard SDK

This is a JavaScript library for generating dashboard definitions for the Cumul.io platform

This library is in alpha state

This is an alpha release. Breaking changes and renaming is expected in future releases. Very much work in progress.

Cumul.io Dashboard SDK

This SDK allows you to programatically generate dashboards for use in the Cumul.io platform. The SDK abstracts away a lot of complexity and enables you to build interactive, multi-tenant & multi-lingual, multi-device dashboards with code just as if they would have been created using the UI.

Why? Cumul.io is API-first and a heavy believer of powerful, convenient API's. Being able to quickly generate interactive dashboards with just a few lines of code is extremely powerful. It allows you to do things like:

• Context-aware dashboards: Show your users a dashboard with information that is relevant for them at that specific time, using their specific situation and any other context.
• In-platform dashboard generator: Allow your users to create dashboards in a playground in your platform. This can be via a UI, a form, a stepper, ... The input from these elements can then be used to generate a dashboard 'on-the-fly' for your users to digest.
• Exception management dashboards: Only show and or highlight information that crossed certain thresholds.
• Change/update dashboards in batch: Did your organization theme change and you do not want to adapt all dashboards manually one by one? Use this SDK to load the existing dashboards, adapt them and update them using Cumul.io's core API.
• ... and so much more

Installation

If you use npm, npm install @cumul.io/dashboard-sdk or yarn yarn install @cumul.io/dashboard-sdk.

This SDK is written using ES6 modules. To import this SDK into an ES2015 application, import everything into a namespace (here, cio):

import * as cio from "@cumul.io/dashboard-sdk";

In Node:

const cio = require("@cumul.io/dashboard-sdk");

Entities

This SDK uses 6 entities (classes) for building dashboards:

• Dashboard: the dashboard itself
• Item: A chart, filter item, text, image, video or spacer.
• Column: A data column used to specify what data is used in an item or filter
• Filter: A filter is used to filter the data used in a dashboard or in an item. Can be used on dashboard or item level.
• Parameter: A parameter is often used in multi-tenant dashboards to adapt filters or the dashboard itself to the parameter value supplied.
• Theme: A theme can be used to style a dashboard or an item. Can be used on dashboard or item level.

What you can do with these entities is described in the following sections.

Dashboard

Create a new empty dashboard

const dashboard = new cio.Dashboard();

Use an existing dashboard definition retrieved via Cumul.io's API

const dashboard = new cio.Dashboard(definition);

Dashboard name Get name:

const nameI18n = dashboard.getName();

Set name:

dashboard.setName('On the fly generated dashboard'); // Sets the name to the dashboards default language
dashboard.setName('On the fly generated dashboard', 'en'); // Sets english name of the dashboard
dashboard.setName({
  en: 'On the fly generated dashboard',
  fr: 'Dashboard généré à la volée'
});  // Sets the full localized name of the dashboard

Set description Get description:

const descriptionI18n = dashboard.getDescription();

Set description:

dashboard.setDescription('This is an example of an SDK generated dashboard'); // Sets the description to the dashboards default language
dashboard.setDescription('This is an example of an SDK generated dashboard', 'en'); // Sets english description of the dashboard
dashboard.setDescription({
  en: 'This is an example of an SDK generated dashboard.',
  fr: 'Ceci est un dashboard généré par un SDK.'
});  // Sets the full localized description of the dashboard

Screen modes Get screen modes:

const screenModes = dashboard.getScreenModes();

Set screen modes in sync:

dashboard.setSyncScreenModes(true);

Desync screen modes:

dashboard.setSyncScreenModes(false);

Add a screen mode:

dashboard.addScreenMode('mobile'); // adds an empty mobile screen mode (if screen modes are not synced)
dashboard.addScreenMode('tablet', 'desktop'); // adds a tablet screen mode (based on the desktop screen mode)

Remove a screen mode:

dashboard.removeScreenMode('tablet');

Columns A dashboard screen mode consists of columns and rows, for positioning of its items. These can differ across screen modes. Get columns:

const dashboardColumns = dashboard.getColumns(); // Retrieves number of columns for abitrary first screen mode
const mobileColumns = dashboard.getColumns('mobile'); // Retrieves number of columns for mobile mode

Set columns:

dashboard.setColumns('24'); // Sets number of columns to 24 for all screen modes
dashboard.setColumns('6', 'mobile'); // Sets number of columns to 6 for mobile screen mode

RowHeight A dashboard screen mode consists of columns and rows, for positioning of its items. These can differ across screen modes. Get row height:

const dashboardRowHeight = dashboard.getRowHeight(); // Retrieves number of columns for abitrary first screen mode
const mobileRowHeight = dashboard.getRowHeight('mobile'); // Retrieves number of columns for mobile mode

Set row height:

dashboard.setRowHeight('16'); // Sets row height to 16px for all screen modes
dashboard.setRowHeight('24', 'mobile'); // Sets row height to 24px for mobile screen mode

Timezone Get dashboard timezone:

const dashboardTimezone = dashboard.getTimezone();

Set dashboard timezone:

dashboard.setTimezone('Etc/GMT+11');

Manage filters Get dashboard filters:

const dashboardFilters = dashboard.getFilters();

Add filter instance to a dashboard, see Filter how to create one:

dashboard.addFilter(filter); // adds the filter to all screenmodes
dashboard.addFilter(filter, 'tablet'); // adds the filter only to screenmode 'tablet'

Remove filter from a dashboard, you can use the filter id or the filter instance:

dashboard.removeFilter(filterId); // removes the filter using the filter id
dashboard.removeFilter(filter); // removes the filter using the filter instance

Manage parameters List all dashboard parameters instances:

const dashboardParameters = dashboard.getParameters();

Add a parameter to a dashboard, see Parameter how to create one:

const dashboard.addParameter(parameter);

Remove a parameter from a dashboard:

dashboard.removeParameter(parameterName); // removes a parameter based on it's name
dashboard.removeParameter(parameter); // removes a parameter using the instance

Export JSON definition To export the json definition for creation with Cumul.io's API or integration Cumul.io's Integration API:

const json = dashboard.toJSON();

You can then use this json object to create a dashboard with Cumul.io's API OR just use the contents and integrate the dashboard in a webpage.

Item

Create a new chart: eg.

const barChart = new cio.BarChart();

Check the list of items for all available charts.

Set title Use a string:

barChart.setTitle('My bar chart');

Use a localized object:

barChart.setTitle({
  en: 'My bar chart',
  fr: 'Ma graphique à barres'
});

Add data

barChart
  .setData('measure', measureColumn, { format:  '.f2', aggregation:  'median' })
  .setData('category', categoryColumn, { label: { en: 'category' } });

Check the Column section how to create a column definition. Check the list of items for data slot possibilities in a chart. When setting data you can supply optional settings such as:

• format: The format you wish to use in case of numeric or datetime data.
• aggregation: The aggregation function you wish to use in case of numeric data. Possibilities are: sum, min, max, median, (TO DO supply all info)
• label: an internationalized string. The label will be used in tooltips when hovering the cursor over a chart.
• level: Numeric. The level of a datetime column (1 to 9: year to millisecond) or of a hierarchy column.

Set an option

barChart
  .setOption('categories.colored', true)
  .setOption('display.title', false);

Check the list of items for all possibilities in a chart.

Add to a dashboard From the dashboard:

dashboard.addItem(barChart);

From the item:

barChart.appendTo(dashboard);

Retrieve the dashboard the item was linked to

barChart.getDashboard();

This returns the dashboard instance linked to the item. This is very useful for chaining.

Set Size Set width & height (in columns & rows):

barChart.setSize({width: 24, height:20}); // if screen modes are synced, sets the size in all screen modes

Set width & height (in columns & rows) in a specific screen modes:

barChart
  .setSize({width: 16, height:16}, 'mobile')
  .setSize({width: 24, height:20}, 'tablet');

You can also only set width or height:

barChart
  .setSize({width: 24}, 'tablet')
  .setSize({height: 20}, 'tablet');

Set Position Set width & height (in columns & rows):

barChart.setPosition({row: 0, column: 12}); // if screen modes are synced, sets the size in all screen modes

Set width & height (in columns & rows) in a specific screen modes:

barChart
  .setPosition({row: 0, column: 12}, 'mobile')
  .setPosition({row: 12, column: 12}, 'tablet');

You can also only set width or height:

barChart
  .setPosition({row: 0}, 'tablet')
  .setPosition({column: 12}, 'tablet');

Clone

const barChartCloned = barChart.clone();

This function returns the cloned item.

Column

Create Create an empty column instance

const column = new cio.Column();

Create a column instance immediately setting its attributes

const definedColumn = new  cio.Column({
  columnId:  columnId,
  datasetId:  datasetId,
  label: { en:  'Column label' },
  type:  'numeric'
});

Column id Get column id

const columnId = column.getColumnId();

Set column id to an existing column id:

column.setColumnId(columnId);

Dataset Id Get column id

const datasetId = column.getDatasetId();

Set dataset id to an existing dataset id:

column.setDatasetId(columnId);

Label
Use a string:

const columnLabelI18n = column.getLabel();

Use a localized object:

column.setLabel('Column Label'); // Sets the label to the default language
column.setLabel('Column Label', 'en'); // Sets english label of the column
column.setLabel({
  en: 'Column Label',
  fr: 'Libellé de la colonne'
});  // Sets the full localized label of the column

The column label is an internationalized string. The label will be used in tooltips when hovering the cursor over a chart.

Type Get column type

const columnType = column.getType();

Set column type:

column.setType('numeric');

Type can be of: "numeric", "hierarchy", "datetime", "spatial".

Subtype Get column subtype

const columnSubtype = column.getSubtype();

Set column subtype:

column.setSubtype('duration');

Type can be of:

• for numeric type: "duration", "currency"
• for spatial type: "topography", "currency"

Set aggregation
Get column aggregation

const columnAggregation = column.getAggregation();

Set column aggregation:

column.setAggregation('median');

Aggregation can be: "sum", "cumulativesum", "average", "median", "count", "distinctcount", "min", "max", "stddev" or "rate"

Set format Get column format

const columnFormat = column.getFormat();

Set column format:

column.setFormat('.f0');

Set level Get column level

const columnFormat = column.getLevel();

Set column level:

column.setLevel(4);

The level of a datetime column (1 to 9: year to millisecond) or of a hierarchy column.

Clone

const clonedColumn = column.clone();

Filter

Create

Create an empty filter instance

const filter = new cio.Filter();

Create a filter instance immediately setting its attributes

const definedFilter = new cio.Filter({
	column: measureColumn,
	expression: '? > ?',
	value: 100
});

Filter column Get column:

filter.getColumn();

Set a column:

filter.setColumn(measureColumn);

Filter expression Get expression:

filter.getExpression();

Set expression:

filter.setExpression('? > ?');

Expressions can be:

• for any column: "? is null" or "? is not null"
• with numeric column: "? = ?", "? != ?", "? in ?", "? not in ?", "? like ?", "? not like ?", "? < ?", "? <= ?", "? > ?", "? >= ?"
• with hierarchy column: "? = ?", "? != ?", "? in ?", "? not in ?", "? starts with ?", "? not starts with ?", "? ends with ?", "? not ends with ?"
• with datetime column: "last_now", "last_available", "last_completed", "to_date", "WTD", "MTD", "QTD", "YTD", "? within ?",

Filter value Get value:

const filterValue = filter.getValue();

Set value:

filterA.setValue(100); // Example for numeric Column
filterA.setValue([100, 150]); // Example for numeric Column with "? in ?" or "? not in ?" expression
filterC.setValue('Awesome Company'); // Example for hierarchy Column
filterD.setValue(['Burrito', 'Fajita']); // Example for hierarchy Column with "? in ?" or "? not in ?" expression
filterE.setValue(column); // Example for value set to a column
filterF.setValue(parameter); // Example for value set to a parameter

Filter value can be of type: number, string, array of numbers, array of strings, Column instance or Parameter instance. Clone

const clonedFilter = filter.clone();

Item filter Add filter to an item:

barChart.addFilter(filter);

Remove filter from an item, you can use the filter id or the filter object:

barChart.removeFilter(filterId); // removes the filter using the filter id
barChart.removeFilter(filter); // removes the filter using the filter instance

Get item filters:

const barChartFilters = barChart.getFilters();

Dashboard filters Add filter to a dashboard:

dashboard.addFilter(filter); // adds the filter to all screenmodes
dashboard.addFilter(filter, 'tablet'); // adds the filter only to screenmode 'tablet'

Remove filter from a dashboard, you can use the filter id or the filter object:

dashboard.removeFilter(filterId); // removes the filter using the filter id
dashboard.removeFilter(filter); // removes the filter using the filter instance

Get dashboard filters:

const dashboardFilters = dashboard.getFilters();

Parameter

Create Create an empty parameter instance

const parameter = new cio.Parameter();

Create a parameter instance immediately setting its attributes

const definedParameter = new cio.Parameter({
  parameter:  'userId',
  type:  'hierarchy',
  value:  '123'
});

Name Get name:

const parameterName = parameter.getName();

Set name:

parameter.setName('company'); // Sets the parameter name to company. Use in multi-tenant embedding.

Default value Get default value:

const parameterDefault = parameter.getDefaultValue();

Set default value:

parameter.setDefaultValue('Awesome company'); // Sets the parameter default value to 'Awesome company'. Use in multi-tenant embedding.

Type Get type:

const parameterType = parameter.getType();

Set type:

parameter.setType('hierarchy'); // Sets the parameter type to hierarchy. Use in multi-tenant embedding.

Types can be: "numeric", "datetime", "hierarchy", "array[hierarchy]" or "array[numeric]"

Dashboard Add a parameter to a dashboard:

Remove a parameter from a dashboard:

dashboard.removeParameter(parameterName); // removes a parameter based on it's name
dashboard.removeParameter(parameter); // removes a parameter using the instance

List all dashboard parameters instances:

const dashboardParameters = dashboard.getParameters();

Theme

Create

const customTheme = new cio.Theme();

Set options

customTheme
  .setOption('background','#262732')
  .setOption('itemsBackground','#343544');

Dashboard theme Setting a theme:

dashboard.setTheme(themeId); // sets a platorm or organization theme using the id
dashboard.setTheme(customTheme); // sets a custom theme using the custom theme instance

Getting a theme:

const dashboardTheme = dashboard.getTheme();

Item theme
Setting a theme:

barChart.setTheme(themeId); // sets a platorm or organization theme using the id
barChart.setTheme(customTheme); // sets a custom theme using the custom theme instance

Getting a theme:

const barChartTheme = barChart.getTheme();

Examples

const  measureColumn = new  cio.Column({
  datasetId:  '5b952cc9-0a44-47b8-bc5a-20edcabca925',
  columnId:  '4125af6f-044a-445e-a392-ca80676fc20c',
  label: { en:  'Volume' },
  type:  'numeric'
}); 

const  dashboard = new  cio.Dashboard();
dashboard
  .setName('Testing the SDK') // uses default 'en'
  .setName('En we zingen met zen allen hip hip hoera', 'nl') // or use a language
  .setDescription({ fr:  'Should create a dashboard json definition' }) // also allows internationalized strings
  .addParameter(new  cio.Parameter({ parameter:  'company', type:  'array[hierarchy]', value: ['Coca-Cola']})) // set Parameter
  .removeParameter('company')
  .addParameter({ parameter:  'companyNew', type:  'array[hierarchy]', value: ['Coca-Cola']})
  .setTimezone('Etc/GMT+11')
  .addItem(
    new  cio.BarChart()
      .setTitle('Chart 1')
      .setSize({ width:  24, height:  20 })
      .setOption('categories.colored', true)
      .setOption('display.title', false)
      .setData('measure', measureColumn, { format:  '.f2', aggregation:  'median' })
  )
  .addItem(
    new  cio.Donut()
     .setTitle('Chart 2')
     .setSize({ width:  24, height:  20 })
  )
  .removeScreenMode('tablet');

const json = dashboard.toJSON();

Remarks

Changelog

List of items

AreaChart BarChart BubbleChart Bullet Choropleth CircleGauge CirclePack ColumnChart CombinationChart Datefilter Donut Funnel Heatmap Hexbinmap Imageobject LineChart Markermap NumberConditional Ohlc OneNumber ParallelCoord PivotTable Pyramid RadarChart RegularTable Routemap Sankey ScatterPlot Selectbox Slicer Slider Spacer Speedometer StripPlot Sunburst Symbolmap Textobject Treemap Videoobject