Creating your own Dashboard Chart plugin

You can create your own Dashboard Chart plugin to add a new analytics widget to the dashboard.

Conditions:

• The new Dashboard Chart class must implement the "DashboardChart" interface.
• The new Dashboard Chart class must be declared under the package "com.openkm.plugin.dashboard".
• The new Dashboard Chart class must be annotated with "@PluginImplementation".
• The new Dashboard Chart class must extend "BasePlugin".

DashboardChart interface:

package com.openkm.plugin.dashboard;

import com.openkm.core.DatabaseException;
import com.openkm.core.RepositoryException;
import net.xeoh.plugins.base.Plugin;

import java.util.Calendar;
import java.util.List;

public interface DashboardChart extends Plugin {

	enum ChartType {
		BAR, BAR_HORIZONTAL, PIE, LINE, TABLE, NESTED_TABLE
	}

	enum Frequency {
		DAILY, WEEKLY, MONTHLY, NEVER
	}

	// Filter key used when the chart has no user-selectable filters
	String DEFAULT_FILTER = "DEFAULT";

	// Common filter keys for a week/month/year breakdown
	String WEEK = "WEEK";
	String MONTH = "MONTH";
	String YEAR = "YEAR";

	String getName();

	String getTitle();

	String getDescription();

	ChartType getChartType();

	Frequency getFrequency();

	int getOrder();

	default int getColumnWidth() {
		return 6;
	}

	default boolean isMultiChart() {
		return false;
	}

	default List<String> getChartInstances() throws DatabaseException {
		return List.of();
	}

	default List<String> getChartInstances(String parent) throws DatabaseException {
		return getChartInstances();
	}

	default String getMultipleLabel() {
		return null;
	}

	default List<String> getFilters() {
		return List.of();
	}

	default List<String> getColumnNames() {
		return List.of();
	}

	default boolean isRefreshEnabled() {
		return false;
	}

	default List<String> getPeriods(String filter, String parent) throws DatabaseException {
		return List.of();
	}

	default boolean isHistoryEnabled() {
		return false;
	}

	void execute() throws RepositoryException, DatabaseException;

	default List<ChartSeries> execute(Calendar from, Calendar to) throws RepositoryException, DatabaseException {
		return List.of();
	}

	default void rebuild() throws RepositoryException, DatabaseException {
	}

	List<ChartSeries> getData(String filter) throws DatabaseException;

	default List<ChartSeries> getData(String filter, String period) throws DatabaseException {
		return getData(filter);
	}

	default List<ChartSeries> getData(String filter, String period, String instance) throws DatabaseException {
		return getData(filter, period);
	}
}

The new class must be loaded into the package com.openkm.plugin.dashboard because the application plugin system will try to load it from there.

Method descriptions

Chart types

Frequency

Testing every combination with SampleChart

SampleChart ships as a test fixture only (getOrder() 999, never assigned to a real profile). It is entirely driven by chart.sample_chart.* OKM_CONFIG keys, so every UI combination a widget can be in can be exercised just by changing a key and reloading the dashboard - no code change or redeploy needed.

PIE (chart.sample_chart.type=pie)

Categories: the 4 fruit names ("Apples", "Pears", "Bananas", "Grapes").

BAR / BAR_HORIZONTAL (chart.sample_chart.type=bar / bar_horizontal)

Both types share the same Vue component under the hood; the only difference is orientation, so the combination matrix is identical for both - only the type value changes.

Categories: the 4 fruit names, sorted by descending value.

LINE (chart.sample_chart.type=line)

Unlike PIE/BAR, the categories here are not fruit: SampleChart detects type=line and uses 7 consecutive days instead, so the line reads as a trend rather than connecting fruit names in alphabetical order.

TABLE (chart.sample_chart.type=table)

Supports everything PIE/BAR/LINE do, except several series per card. Since a table never shows a series name anywhere, SampleChart suffixes each row with the resolved instance for this type only - "Apples ? North region" instead of just "Apples" - so the instance value (from either multipart or multiple_label) is visibly confirmed to reach getData().

NESTED_TABLE (chart.sample_chart.type=nested_table)

A distinct type, not a combination of flags on top of TABLE. It is the only case where the outer split and the inner dropdown combine - and they always do, regardless of multipart, which is ignored entirely for this type.

It uses its own two-level invented dataset, independent of the fruit/instance one used above: 2 workflows ("Contract approval", "Expense report"), each with its own 2-3 tasks, and 3 users (Alice, Bob, Carol) as rows. Set chart.sample_chart.multiple_label=Task so the inner dropdown has a label to identify it by.

Example

SampleChart class:

package com.openkm.plugin.dashboard;

import com.openkm.core.DatabaseException;
import com.openkm.db.service.ConfigSrv;
import com.openkm.plugin.BasePlugin;
import lombok.extern.slf4j.Slf4j;
import net.xeoh.plugins.base.annotations.PluginImplementation;
import org.springframework.beans.factory.annotation.Autowired;

import java.time.LocalDate;
import java.util.ArrayList;
import java.util.List;
import java.util.Map;
import java.util.Objects;
import java.util.stream.Collectors;

/**
 * Throwaway test fixture, not a real metric - invented data entirely driven by the chart.sample_chart.*
 * OKM_CONFIG keys, to exercise every UI combination a widget can be in without touching code or
 * redeploying. See "Testing every combination with SampleChart" above for the full list of keys and
 * combinations.
 */
@Slf4j
@PluginImplementation
public class SampleChart extends BasePlugin implements DashboardChart {
	private static final String TYPE_CONFIG_KEY = "chart.sample_chart.type";
	private static final String MULTI_CHART_CONFIG_KEY = "chart.sample_chart.multipart";
	private static final String MULTIPLE_LABEL_CONFIG_KEY = "chart.sample_chart.multiple_label";
	private static final String SERIES_COUNT_CONFIG_KEY = "chart.sample_chart.series_count";
	private static final String FILTERS_ENABLED_CONFIG_KEY = "chart.sample_chart.filters_enabled";
	private static final String HISTORY_ENABLED_CONFIG_KEY = "chart.sample_chart.history_enabled";
	private static final String REFRESH_ENABLED_CONFIG_KEY = "chart.sample_chart.refresh_enabled";

	private static final List<String> INSTANCES = List.of("North region", "South region", "East region");
	private static final List<String> FRUITS = List.of("Apples", "Pears", "Bananas", "Grapes");
	private static final List<String> YEARS = List.of("2024", "2025", "2026");

	// NESTED_TABLE's own two-level invented dataset (outer workflow -> inner tasks)
	private static final List<String> WORKFLOWS = List.of("Contract approval", "Expense report");
	private static final Map<String, List<String>> TASKS_BY_WORKFLOW = Map.of(
			"Contract approval", List.of("Legal review", "Manager sign-off", "Archive"),
			"Expense report", List.of("Manager approval", "Finance check"));
	private static final List<String> USERS = List.of("Alice", "Bob", "Carol");

	private static final int LINE_DAYS = 7;

	@Autowired
	private ConfigSrv configSrv;

	@Override
	public String getName() {
		return "Sample chart (test)";
	}

	@Override
	public String getTitle() {
		return "Sample chart (test)";
	}

	@Override
	public String getDescription() {
		return "Throwaway fixture with invented data, entirely driven by chart.sample_chart.* OKM_CONFIG keys.";
	}

	@Override
	public ChartType getChartType() {
		return switch (configString(TYPE_CONFIG_KEY, "pie").toLowerCase()) {
			case "bar" -> ChartType.BAR;
			case "bar_horizontal" -> ChartType.BAR_HORIZONTAL;
			case "line" -> ChartType.LINE;
			case "table" -> ChartType.TABLE;
			case "nested_table" -> ChartType.NESTED_TABLE;
			default -> ChartType.PIE;
		};
	}

	@Override
	public Frequency getFrequency() {
		return Frequency.NEVER;
	}

	@Override
	public int getOrder() {
		return 999;
	}

	@Override
	public boolean isMultiChart() {
		return configBoolean(MULTI_CHART_CONFIG_KEY, false);
	}

	@Override
	public List<String> getChartInstances() {
		return getChartType() == ChartType.NESTED_TABLE ? WORKFLOWS : INSTANCES;
	}

	@Override
	public List<String> getChartInstances(String parent) {
		if (getChartType() == ChartType.NESTED_TABLE && parent != null) {
			return TASKS_BY_WORKFLOW.getOrDefault(parent, List.of());
		}

		return getChartInstances();
	}

	@Override
	public String getMultipleLabel() {
		String label = configString(MULTIPLE_LABEL_CONFIG_KEY, "");
		return label.isBlank() ? null : label;
	}

	@Override
	public List<String> getFilters() {
		return configBoolean(FILTERS_ENABLED_CONFIG_KEY, false) ? List.of(WEEK, MONTH, YEAR) : List.of();
	}

	@Override
	public boolean isHistoryEnabled() {
		return configBoolean(HISTORY_ENABLED_CONFIG_KEY, false);
	}

	@Override
	public List<String> getPeriods(String filter, String parent) {
		if (!isHistoryEnabled()) {
			return List.of();
		}

		return switch (filter) {
			case YEAR -> YEARS;
			case MONTH -> parent != null ? monthsOf(parent) : List.of();
			case WEEK -> parent != null ? weeksOf(parent) : List.of();
			default -> List.of();
		};
	}

	@Override
	public boolean isRefreshEnabled() {
		return configBoolean(REFRESH_ENABLED_CONFIG_KEY, false);
	}

	@Override
	public List<String> getColumnNames() {
		return getChartType() == ChartType.NESTED_TABLE ? List.of("User", "Average time (invented)") : List.of("Fruit", "Sales");
	}

	@Override
	public void execute() {
		// Never called - see getFrequency()
	}

	@Override
	public List<ChartSeries> getData(String filter) {
		return getData(filter, null, INSTANCES.get(0));
	}

	@Override
	public List<ChartSeries> getData(String filter, String period, String instance) {
		if (getChartType() == ChartType.NESTED_TABLE) {
			return nestedTableData(instance);
		}

		boolean isLine = getChartType() == ChartType.LINE;
		boolean isTable = getChartType() == ChartType.TABLE;
		List<String> categories = isLine ? lastDays(LINE_DAYS) : FRUITS;
		String baseName = isLine ? "Daily activity (invented)" : "Fruit sales (invented)";
		int seriesCount = Math.max(1, configInt(SERIES_COUNT_CONFIG_KEY, 1));
		List<ChartSeries> series = new ArrayList<>();

		for (int s = 0; s < seriesCount; s++) {
			List<ChartDataPoint> points = new ArrayList<>();

			for (String category : categories) {
				points.add(new ChartDataPoint(rowLabel(category, instance, isTable), fakeValue(instance, filter, period, s, category)));
			}

			String seriesName = seriesCount == 1 ? baseName : baseName + " - batch " + (s + 1);
			series.add(new ChartSeries(seriesName, points));
		}

		return series;
	}

	// instance arrives as "workflow::task" - see ChartControls.vue's effectiveInstance
	private List<ChartSeries> nestedTableData(String instance) {
		if (instance == null || !instance.contains("::")) {
			return List.of();
		}

		String[] parts = instance.split("::", 2);
		String workflow = parts[0];
		String task = parts[1];

		List<ChartDataPoint> points = USERS.stream()
				.map(user -> new ChartDataPoint(user, fakeValue(instance, null, null, 0, user)))
				.collect(Collectors.toList());

		return List.of(new ChartSeries("Average time (invented) ? " + workflow + " / " + task, points));
	}

	// TABLE-only: suffix each row with the instance so it's visible which instance produced it
	private String rowLabel(String category, String instance, boolean isTable) {
		return (isTable && instance != null) ? category + " ? " + instance : category;
	}

	private List<String> lastDays(int days) {
		LocalDate today = LocalDate.now();
		List<String> labels = new ArrayList<>();

		for (int i = days - 1; i >= 0; i--) {
			labels.add(today.minusDays(i).toString());
		}

		return labels;
	}

	// Deterministic (not random) so the same combination always renders the same numbers
	private double fakeValue(String instance, String filter, String period, int seriesIndex, String category) {
		int seed = mix32(Objects.hash(instance, filter, period, seriesIndex, category));
		return 5 + (Math.abs(seed) % 46);
	}

	private int mix32(int x) {
		x ^= (x >>> 16);
		x *= 0x7feb352d;
		x ^= (x >>> 15);
		x *= 0x846ca68b;
		x ^= (x >>> 16);
		return x;
	}

	private List<String> monthsOf(String year) {
		List<String> months = new ArrayList<>();
		for (int month = 1; month <= 12; month++) {
			months.add(String.format("%s-%02d", year, month));
		}
		return months;
	}

	private List<String> weeksOf(String month) {
		List<String> weeks = new ArrayList<>();
		for (int week = 1; week <= 4; week++) {
			weeks.add(month + "-W" + week);
		}
		return weeks;
	}

	private String configString(String key, String defaultValue) {
		try {
			return configSrv.getString(key, defaultValue);
		} catch (DatabaseException e) {
			log.warn("Could not read '{}', defaulting to '{}': {}", key, defaultValue, e.getMessage());
			return defaultValue;
		}
	}

	private boolean configBoolean(String key, boolean defaultValue) {
		try {
			return configSrv.getBoolean(key, defaultValue);
		} catch (DatabaseException e) {
			log.warn("Could not read '{}', defaulting to {}: {}", key, defaultValue, e.getMessage());
			return defaultValue;
		}
	}

	private int configInt(String key, int defaultValue) {
		try {
			return configSrv.getInteger(key, defaultValue);
		} catch (DatabaseException e) {
			log.warn("Could not read '{}', defaulting to {}: {}", key, defaultValue, e.getMessage());
			return defaultValue;
		}
	}
}