Skip to main content

Dashboards

Dashboards provide a comprehensive view of data, offering a visual representation that makes it easier to identify patterns, trends, and insights. They are a powerful tool for developers, analysts, and leaders working with and trying to understand the vast amounts of data generated in web3.

A dashboard is composed of a series of rows, each containing one or more panels. These panels are the building blocks of your dashboard, each serving as a window into a specific subset of data.

Each panel is connected to one or more data sources and employs a specific rendering strategy to display the data. This could be in the form of graphs, charts, or tables for blockchain or other data, images, or static data for fixed information.

With the flexibility of our dashboard panels, you can customize your dashboard to meet your specific needs. For example, you could create a panel that displays how the state of your contract is changing over time, a panel that compares the current price of a token from multiple sources, or a panel that displays metrics based on contract log events emitted over time. This ensures that the most relevant data is always at your fingertips.

Dashboard Schema​

Dashboards definitions are JSON documents. For the most up-to-date schema refer to the Metric Dashboard API Swagger Docs.

The following are properties available at the time of writing.

  • id: (string) The unique id for this dashboard.
  • owner: (string) The user who owns the dashboard.
  • name: (string) A user-friendly name for this dashboard.
  • description: (string) A user-friendly description for this dashboard.
  • rows: (array) an array of objects. A row is made up of an array of panels
  • tags: (object) Any tags (key/value pairs of strings) associated with the dashboard.
  • interval
    • defaultValue: (string) The default interval to use for the dashboard.
    • hide: (boolean) If true, the interval selector should be hidden on this dashboard.
    • choices: (object) An object of type DashboardChoicesStatic.
  • timeRange
    • defaultValue: (object) The default time range for the dashboard.
      • from: The default start time for the dashboard. Use now-{amount} for relative time or an ISO time stamp for a absolute time.
      • to: The default end time for the dashboard. Use now for the current time or an ISO time stamp for a absolute time.
    • hide: (boolean) If true, the time range selector should be hidden on this dashboard.
  • variables: (array) An array of DashboardVariable objects.
    • name: (string) The variable name that will be used in the queries.
    • defaultValue: (string) The default initial value for the variable.
    • label: (string) The label to display for the variable name input in the frontend.
    • type: (string) The type of thing the variable is.
    • hide: (boolean) If true, the variable should be hidden from the person viewing the dashboard.
    • choices: (object) An object of type DashboardChoicesStatic or DashboardChoicesLookup.
  • createdDt: (string) The date and time when the dashboard was created.
  • updatedDt: (string) The date and time when the dashboard was last updated.

Dashboard Panels​

Dashboard panels are the building blocks of dashboards. Each row of a dashboard has one or more panels. Currently four types of dashboard panels are supported. Every dashboard panel has the following common properties:

  • panelType allows us to know how to render the panel and defines which properties are available.
  • span Defines the proportion of the screen this panel should take up in its row. Should be between 0 and 1. All panels in a single row should add to 1.
  • links: Refer to DashboardPanelLink

DashboardPanelChart​

The DashboardPanelChart object allows you to customize the appearance and behavior of a dashboard panel chart.

  • panelType: "rule" (or deprecated "chart")
  • network: mainnet or testnet
  • rules: An array of rules to add to a panel, with optional label if adding multiple. Each rule object has the following properties:
    • id: The alarm id to add to the panel's graph.
    • label: Optional label for the rule to show in the legend. Only useful for multi-rule panels.
    • enableTableData: Optional boolean to enable click through to raw events table for rule.
  • span: number between 0 and 1
  • name: Give your panel a short descriptive name.
  • description: Add a longer description if you dare.
  • chartType: The chart type defines how the data should be rendered. (scatter, line, area, bar, pie (sum), pie (latest), stacked bar, number (sum), number (latest), table, etc)
  • links: Refer to DashboardPanelLink.
  • config: Refer to DashboardPanelConfig.

Example:

{
  "panelType": "chart",
  "network": {},
  "rules": [
    {
      "id": "1b4657e7-6720-4c73-8553-cc170c94d273",
      "label": "Withdrawals"
    },
    {
      "id": "3a4657e7-6720-4c73-8553-cc170c94d425",
      "label": "Deposits",
      "enableTableData": false
    }
  ],
  "span": {},
  "name": "Example Panel",
  "description": "This is an example panel.",
  "chartType": "line",
  "links": {},
  "config": {}
}

*Required properties: network, span, chartType, panelType

DashboardPanelQuery​

The DashboardPanelQuery object allows you to customize the appearance and behavior of a dashboard panel query.

  • panelType: "query"
  • network: mainnet or testnet
  • queries: An array of queries to run to get data for a panel, with optional label if adding multiple. Each query object has the following properties:
    • query: The SQL query to run to get data to display in the panel.
    • label: Optional label for the query to show in the legend. Only useful for multi-query panels.
  • span: number between 0 and 1.
  • name: Give your panel a short descriptive name.
  • description: Add a longer description if you dare.
  • chartType: The chart type defines how the data should be rendered. (scatter, line, area, bar, pie (sum), pie (latest), stacked bar, number (sum), number (latest), table, etc)
  • links: Refer to DashboardPanelLink.
  • config: Refer to DashboardPanelConfig.

Example:

{
  "panelType": "query",
  "network": {},
  "queries": [
    {
      "query": "select time, val from transactions",
      "label": "Transactions"
    },
    {
      "query": "select time, val from contract_logs",
      "label": "Contract Logs"
    }
  ],
  "span": {},
  "name": "Example Panel",
  "description": "This is an example panel.",
  "chartType": "line",
  "links": {},
  "config": {}
}

*Required properties: network, span, chartType, panelType

DashboardPanelStaticImage​

The DashboardPanelStaticImage object allows you to customize the appearance and behavior of a static image panel on the dashboard.

  • panelType: "image".
  • span: number between 0 and 1.
  • content: A url to load the image for this panel.
  • alt: The alt text for the image.
  • links: Refer to DashboardPanelLink.

Required properties: span, content, panelType

DashboardPanelStaticBasic​

The DashboardPanelStaticBasic object allows you to customize the appearance and behavior of a basic static panel on the dashboard. This can be either a text or markdown panel.

  • panelType: For a basic static panel, this should be either "text" or "markdown".
  • span: number between 0 and 1.
  • content: The static content for this panel.
  • links: Refer to DashboardPanelLink.

Required properties: span, content, panelType

Reference Schemas​

DashboardPanelConfig​

The DashboardPanelConfig object allows you to customize the appearance and behavior of a dashboard panel. This configuration can be used to add threshold lines to a chart or to customize table formatting.

Thresholds​

Thresholds are lines that can be added to a chart to indicate certain values. Each threshold has a value (val) that determines where it falls on the y-axis and an optional color (color). If no color is specified, the threshold line defaults to red.

Example:

{
  "thresholds": [
    {
      "val": 50,
      "color": "blue"
    }
  ]
}

Table​

The table object allows you to customize a table type chart. It includes settings for pinned columns, hidden columns, density, and cell formatting.

Pinned Columns​

Pinned columns are columns that remain fixed while the user scrolls horizontally. You can specify columns to pin to the left or right of the table.

Example:

{
  "table": {
    "pinnedColumns": {
      "left": ["column1", "column2"],
      "right": ["column3"]
    }
  }
}

Hidden Columns​

Hidden columns are columns that are hidden when the table renders.

Example:

{
  "table": {
    "hiddenColumns": ["column1", "column2"]
  }
}

Density​

The density property controls the vertical padding of the table rows. It can be set to "compact", "standard", or "comfortable".

Example:

{
  "table": {
    "density": "compact"
  }
}

Formatting​

The formatting property is an array that allows you to apply custom formatting to the cells in the table. Each item in the array is an object that specifies the columns to apply the formatting to, a condition to determine which cells to format, and the format to apply.

Columns​

The columns property is an array of strings that specifies the columns to apply the formatting to. If not specified, the formatting will be applied to all columns.

Condition​

The condition property is a Jsonlogic predicate condition that is evaluated for each cell in the table. Any cell that resolves to true and is included in the column selection will be formatted. The following fields are available for use in the jsonlogic:

  • header: The name of the column currently being formatted
  • value: The value of the cell currently being formatted
  • column: An array of column values for the cell currently being formatted
  • row: The row of the cell currently being formatted as an object. The headers of the table are the keys.
  • tableData: The entire table data as an array of objects. Each object is a row with the headers as keys.
Format​

The format property is an object that specifies the formatting to apply to the cells that match the condition. Any property that is not set will not be applied. The available properties are:

  • bold: Makes the text bold. Accepts a boolean value.
  • color: Sets the text color. Accepts a string with a valid color name or hex color code.
  • backgroundColor: Sets the background color of the cell. Accepts a string with a valid color name or hex color code.
  • fontSize: Sets the size of the text. Accepts small or large.
  • italic: Makes the text italic. Accepts a boolean value.
  • underline: Underlines the text. Accepts a boolean value.
  • justify: Sets the text alignment. Accepts left, center, or right.
  • className: Applies a CSS class to the cell. Accepts a string with the class name.
  • valueTransformer: A JsonLogic transformer to apply to the cell's value before display. This gets applied before the stringFormat gets applied; any references to {{value}} in the stringFormat will use the result of this transformer if provided.
  • stringFormat: The string format to apply to the cell. This is a template string that can include variables. Variables are wrapped in double curly braces. The following variables are available for use:
    • {{value}}: the cell value after formatting transformations are applied.
    • {{rawValue}}: the cell value before formatting transformations are applied.
    • {{header}}: the name of the column this cell belongs to, i.e. the column header.
    • {{row.otherColumn}}: reference another value in the row this cell belongs to. Replace "otherColumn" with the name of the column you want to reference.
    • {{explorerUrl}}: the explorer url for the network and chain the row belongs to.
    • {{appOriginUrl}}: The lworks app origin url.
    • {{dashboardVariableName}}: Dashboard variables are also available for use in the stringFormat. Replace "dashboardVariableName" with the name of the variable you want to reference.
  • link: The url to link to if the cell is clicked. Links are evaluated the same as stringFormat and have all the same context available, but are expected to yield a valid href.

Example:

{
  "table": {
    "formatting": [
      {
        "columns": ["column1", "column2"],
        "condition": {"<": [{ "var": "value" }, 50]},
        "format": {
          "bold": true,
          "color": "red",
          "backgroundColor": "yellow",
          "fontSize": "large",
          "italic": true,
          "underline": true,
          "justify": "center",
          "className": "my-class",
          "valueTransformer": {
            "uppercase": [
              {"var": "value"}
            ]
          },
          "stringFormat": "The value of {{header}} is {{value}}",
          "link": "{{explorerUrl}}/accounts/{{value}}"
        }
      }
    ]
  }
}

DashboardChoicesStatic​

  • kind: (string) "list-with-values" (or deprecated "static")
  • items: (array) The list of choices.
  • allowedChoicesOnly: (boolean) If true, only the choices in the items list are allowed. If false, the user can enter any value.

DashboardChoicesLookup​

  • kind: (string) "metrics-api"
  • path: (string) The path to the lookup to use for the choices.
  • allowedChoicesOnly: (boolean) If true, only the choices in the items list are allowed. If false, the user can enter any value.

The DashboardPanelLink object allows you to add links to the panel.

DashboardPanelLink is an array of objects, each with the following properties:

  • label: The text in the button for the link.
  • href: The absolute or relative URL.
[
  {
    "label": "Another dashboard",
    "href": "https://app.lworks.io/dashboards/board/b20d600a-0531-401b-9597-e00ff2a1e77e"
  }
]