Custom Plugin

Build your own custom plugin to view and filter existing data

For most use cases, you'll want to create a plugin inside a schema. Click here to view the documentation for creating schema plugins.

Configuring Custom Plugin

From your service overview page, select the Add Plugin button.

From the Plugins dialog, browse through the list of available plugins and select the Custom Plugin plug-in by clicking on the Add button.

This will bring you to the custom plugin editor, which will be empty by default.

Custom Plugin JSON Format

A custom plugin is created by specifying an array of plugin option objects. The objects must follow this format:

export type ICustomPluginSchema = ICustomPluginList | ICustomPluginCard | ICustomPluginDivider;

export interface ICustomPluginList {
  displayType: "list";
  schema: string;
  title?: string;
  item?: {
    title: string;
    subtitle?: string;
    color?: string;
    icon?: string;
    tags?: string;
    url?: string;
  };
  maxItems?: number;
  sort?: IQueryBuilderSort;
  filters?: IQueryBuilderFilterCondition[];
}

export interface ICustomPluginCard {
  displayType: "card";
  schema: string;
  title?: string;
  item?: {
    title: string;
    subtitle?: string;
    icon?: string;
    url?: string;
  };
  maxItems?: number;
  sort?: IQueryBuilderSort;
  filters?: IQueryBuilderFilterCondition[];
}

export interface ICustomPluginTable {
  displayType: "table";
  schema: string;
  path?: string;
  title?: string;
  menu?: ICustomPluginMenu;
  sort?: IDataFlexibilitySort;
  filters?: IDataFlexibilityFilterCondition[];
  pageSize?: number;
  columns?: string[];
}

export interface ICustomPluginDivider {
  displayType: "divider";
  title?: string;
}

export enum QueryBuilderSortDirection {
  ASC = 'ASC',
  DESC = 'DESC',
}

export interface IQueryBuilderSort {
  field: string;
  direction: QueryBuilderSortDirection;
}

export enum QueryBuilderFilterType {
  compare = 'compare',
  or = 'or',
  and = 'and',
}

export type IQueryBuilderFilterCondition =
  | IQueryBuilderFilterCompare
  | IQueryBuilderFilterOr
  | IQueryBuilderFilterAnd;

export interface IQueryBuilderFilterCompare {
  type: QueryBuilderFilterType.compare;
  field: string;
  value: string | number | boolean | (string | number)[] | null;
  compare: QueryBuilderFilterCompare;
}

export interface IQueryBuilderFilterOr {
  type: QueryBuilderFilterType.or;
  conditions: IQueryBuilderFilterCondition[];
}

export interface IQueryBuilderFilterAnd {
  type: QueryBuilderFilterType.and;
  conditions: IQueryBuilderFilterCondition[];
}

export interface ICustomPluginChart {
  displayType: "chart";
  variant: "line" | "steppedLine" | "bar" | "stackedBar" | "doughnut";
  schema: string;
  path?: string;
  title?: string;
  options?: {
    valueLabel?: string;
    data?: string;
    label?: string;
    colors?: string[];
    xAxis?: string;
  };
  filters?: IDataFlexibilityFilterCondition[];
}

This likely looks more complicated than it actually is, especially since we allow complex filtering and sorting. Here's a simple example just to show a list of items with some detailed information inline:

[{
    "displayType": "list",
    "schema": "<your_schema_name_here>",
    "item": {
        "title": "{{ item.name }}",
        "subtitle": "{{ item.description }}"
    }
}]

And switching displayType to card looks like this:

The editor on the left-hand side will give you some hints if there are issues in the formatting for the code:

Complex examples

Here are a couple more examples of custom plugins with some varying configurations.

List View

This is an example of a plugin with some more detailed data, as well as a max number for the list of items.

Code snippet

[{
    "schema": "<your_schema_here>",
    "displayType": "list",
    "item": {
        "title": "{{ item.name }}",
        "subtitle": "{{ item.severity }}",
        "icon": "{{ item.priority }}"
    },
    "maxItems": 3
}]

This is an example of a plugin with filtering and sorting.

Code snippet

[{
    "schema": "<your_schema_here>",
    "displayType": "list",
    "item": {
        "title": "{{ item.name }}",
        "subtitle": "{{ item.severity }}"
    },
    "filters": [{
        "type": "compare",
        "field": "name",
        "value": "CVE-2024-0193",
        "compare": "like"
    }]
}]

Table View

This is an example of a plugin with basic configuration

Code snippet

[{
    "displayType": "table",
    "schema": "<your_schema_here>",
}]

This is an example of a plugin with custom page size and sorting.

Code snippet

[{
    "displayType": "table",
    "schema": "scorecards",
    "pageSize": 12,
    "sort": {
        "field": "evaluatePercentage",
        "direction": "ASC"
    },
}]

This is an example of a plugin with filtering.

Code snippet

[{
    "displayType": "table",
    "schema": "scorecards",
    "pageSize": 12,
    "sort": {
        "field": "evaluatePercentage",
        "direction": "ASC"
    },
     "filters": [{
        "type": "compare",
        "field": "evaluatePercentage",
        "value": 10,
        "compare": "gte"
    }],
}]

This is an example of a plugin with custom columns.

Code snippet

[{
    "displayType": "table",
    "schema": "scorecards",
    "pageSize": 12,
    "sort": {
        "field": "evaluatePercentage",
        "direction": "ASC"
    },
     "filters": [{
        "type": "compare",
        "field": "evaluatePercentage",
        "value": 10,
        "compare": "gte"
    }],  
    "columns": ["name","evaluatePercentage"]
}]

Custom Charts

This is an example of a SteppedLine Chart

Code snippet Stepped Line Chart

[{
    "displayType": "chart",
    "schema": "scorecards",
    "variant": "steppedLine",
    "options": {
        "valueLabel": "{{ item.serviceLevels.name }}",
        "data": "{{ item.serviceLevels.services }}",
        "colors": ["purple", "green"],
        "xAxis": "{{ item.name }}"
    }
}]

This is an example of a Line Chart

Code snippet Line Chart

[{
    "displayType": "chart",
    "schema": "scorecards",
    "variant": "line",
    "options": {
        "valueLabel": "{{ item.serviceLevels.name }}",
        "data": "{{ item.serviceLevels.services }}",
        "colors": ["purple", "green"],
        "xAxis": "{{ item.name }}"
    }
}]

This is an example of a Stacked Bar Chart

Code snippet Stacked Bar Chart

[{
    "displayType": "chart",
    "schema": "scorecards",
    "variant": "stackedBar",
    "options": {
        "valueLabel": "{{ item.serviceLevels.name }}",
        "data": "{{ item.serviceLevels.services }}",
        "colors": ["purple", "green"],
        "xAxis": "{{ item.name }}"
    }
}]

This is an example of a Bar Chart

Code snippet Bar Chart

[{
    "displayType": "chart",
    "schema": "scorecards",
    "variant": "bar",
    "options": {
        "valueLabel": "{{ item.serviceLevels.name }}",
        "data": "{{ item.serviceLevels.services }}",
        "colors": ["purple", "green"],
        "label": "Levels"
    }
}]

This is an example of a Doughnut Chart

Code snippet Doughnut Chart

[{
    "displayType": "chart",
    "schema": "scorecards",
    "variant": "doughnut",
    "options": {
        "valueLabel": "{{ item.serviceLevels.name }}",
        "data": "{{ item.serviceLevels.services }}",
        "colors": ["purple", "green"],
        "label": "Badges"
    }
}]