Dashboard Designer Guide

Build interactive, real-time dashboards with charts, metrics, and live data from multiple sources.

📸 Screenshot Needed: Dashboard Designer main interface showing the canvas area with element palette on the left. Navigate to DataMagik → Dashboards → Edit or Create New Dashboard to capture this.

Table of Contents

1. Overview
2. Creating a Dashboard
3. Data Sources
4. Adding Elements
5. Chart Types
6. Metric Cards
7. Data Tables
8. Screen Parameters
9. Layout & Styling
10. Best Practices

1. Overview

The Dashboard Designer allows you to create interactive, real-time dashboards that display data from various sources. Dashboards can include:

• Charts — Line, bar, pie, doughnut, radar, and more
• Metric Cards — KPIs and key numbers with change indicators
• Data Tables — Tabular data with sorting and filtering
• Text Blocks — Labels, headers, and descriptions
• Embedded Dashboards — Nest dashboards within dashboards

Key Features:

• Drag & Drop — Visual layout with resizable elements
• Multiple Data Sources — Static, webhook, or Script Engine
• Auto-Refresh — Keep dashboards updated in real-time
• Screen Parameters — Dynamic filtering and customization
• Responsive Grid — Automatically adjusts to screen size

2. Creating a Dashboard

Step 1: Navigate to Dashboards

Go to DataMagik → Dashboards in the main menu.

Step 2: Create New Dashboard

Click the New Dashboard button.

Step 3: Configure Settings

In the left sidebar, configure your dashboard:

SettingDescriptionDefaultDashboard NameIdentifier for your dashboardRequiredDescriptionWhat this dashboard showsOptionalRefresh IntervalHow often to reload data60 secondsAuto-refresh enabledToggle automatic updatesOn

📸 Screenshot Needed: Dashboard Settings panel showing name, description, and refresh interval fields.

Step 4: Choose Data Source

Select your default data source type:

• Static Data — Hardcoded values for testing
• Webhook — External API endpoint
• Script Engine — Use a DataMagik script
• Mixed — Configure per element

Step 5: Add Elements

Drag elements from the palette onto the canvas.

3. Data Sources

Static Data

Best for testing or fixed values that rarely change.

{
  "sales": [
    { "month": "Jan", "revenue": 45000 },
    { "month": "Feb", "revenue": 52000 },
    { "month": "Mar", "revenue": 48000 }
  ],
  "totalRevenue": 145000,
  "averageOrder": 125.5
}

Webhook Data Source

Connect to any REST API endpoint.

Configuration:

FieldDescriptionWebhook URLFull URL including protocolMethodGET or POSTAuth TypeNone, Bearer Token, API Key, or Basic Auth

📸 Screenshot Needed: Webhook configuration panel showing URL, method, and auth type selectors.

Testing Your Webhook:

1. Configure the URL and authentication
2. Click Test Webhook
3. View the response preview
4. Use the Data Explorer to map fields to elements

Script Engine Data Source

Use a DataMagik script to fetch and transform data.

Configuration:

1. Select a script from the dropdown
2. Click Test Script to preview output
3. Map script output fields to dashboard elements

📸 Screenshot Needed: Script Engine configuration showing script dropdown and test button.

Example Script for Dashboard:

function main(context) {
  // Fetch data from ERP
  const orders = tables.query("SELECT * FROM orders WHERE date >= ?", [
    context.startDate || new Date().toISOString().slice(0, 10),
  ]);

  // Calculate metrics
  const totalRevenue = orders.reduce((sum, o) => sum + o.total, 0);
  const orderCount = orders.length;

  // Group by status
  const byStatus = {};
  orders.forEach((o) => {
    byStatus[o.status] = (byStatus[o.status] || 0) + 1;
  });

  return {
    orders: orders,
    totalRevenue: totalRevenue,
    orderCount: orderCount,
    statusBreakdown: Object.entries(byStatus).map(([status, count]) => ({
      status,
      count,
    })),
  };
}

Mixed Data Sources

Configure each element with its own data source:

1. Set Default Data Source to Mixed
2. When adding/editing elements, choose the source for each
3. Different elements can pull from different APIs or scripts

4. Adding Elements

Element Palette

The left sidebar contains all available elements:

Charts:

• Line Chart
• Bar Chart
• Pie Chart
• Doughnut
• Polar Area
• Radar
• Scatter
• Bubble
• Area (Ribbon)
• Horizontal Bar
• Stepped Line
• Stepped Area

Other Elements:

• Metric Card
• Text Block
• Data Table
• Embed Dashboard

Drag & Drop

1. Click an element in the palette
2. Drag it onto the canvas
3. Drop where you want it
4. Resize by dragging corners/edges
5. Move by dragging the element body

Element Properties

Click any element on the canvas to open the Properties Panel:

📸 Screenshot Needed: Properties Panel showing configuration options for a chart element.

5. Chart Types

Line Chart

Best for showing trends over time.

Data Format:

{
  "labels": ["Jan", "Feb", "Mar", "Apr", "May"],
  "datasets": [
    {
      "label": "Revenue",
      "data": [12000, 19000, 15000, 22000, 18000]
    }
  ]
}

Configuration Options:

• Title
• X-Axis label
• Y-Axis label
• Line tension (curved vs straight)
• Fill area under line
• Show data labels

Bar Chart

Best for comparing categories or discrete values.

Data Format:

{
  "labels": ["Product A", "Product B", "Product C"],
  "datasets": [
    {
      "label": "Sales",
      "data": [450, 320, 280],
      "backgroundColor": ["#4F46E5", "#10B981", "#F59E0B"]
    }
  ]
}

Configuration Options:

• Horizontal or vertical orientation
• Stacked mode
• Bar width
• Background colors
• Border colors

Pie & Doughnut Charts

Best for showing proportions of a whole.

Data Format:

{
  "labels": ["Category A", "Category B", "Category C"],
  "datasets": [
    {
      "data": [30, 50, 20],
      "backgroundColor": ["#EF4444", "#3B82F6", "#10B981"]
    }
  ]
}

Configuration Options:

• Cutout percentage (doughnut only)
• Show legend
• Show percentage labels
• Animation

Radar Chart

Best for comparing multiple variables across categories.

Data Format:

{
  "labels": ["Speed", "Power", "Defense", "Range", "Accuracy"],
  "datasets": [
    {
      "label": "Player A",
      "data": [80, 90, 70, 85, 75]
    },
    {
      "label": "Player B",
      "data": [65, 75, 95, 60, 90]
    }
  ]
}

Scatter & Bubble Charts

Best for showing relationships between variables.

Scatter Data:

{
  "datasets": [
    {
      "label": "Data Points",
      "data": [
        { "x": 10, "y": 20 },
        { "x": 15, "y": 25 },
        { "x": 20, "y": 30 }
      ]
    }
  ]
}

Bubble Data (includes radius):

{
  "datasets": [
    {
      "label": "Sales by Region",
      "data": [
        { "x": 10, "y": 20, "r": 15 },
        { "x": 15, "y": 25, "r": 10 },
        { "x": 20, "y": 30, "r": 20 }
      ]
    }
  ]
}

Advanced Chart Configuration

For complex charts, use the Advanced Chart Editor:

1. Click Advanced on any chart element
2. Edit the raw Chart.js configuration JSON
3. Preview changes in real-time
4. Apply when satisfied

📸 Screenshot Needed: Advanced Chart Configuration modal showing JSON editor and live preview.

6. Metric Cards

Display key performance indicators prominently.

Configuration

PropertyDescriptionTitleMetric name (e.g., "Total Revenue")Value FieldData path to the value (e.g., totalRevenue)FormatNumber, Currency, PercentagePrefixText before value (e.g., "$")SuffixText after value (e.g., "%")Comparison ValuePrevious period value for trendTrendUp/Down arrow based on comparison

Example Metric Card Setup

Data:

{
  "currentRevenue": 145000,
  "previousRevenue": 132000,
  "percentChange": 9.85
}

Configuration:

• Title: "Monthly Revenue"
• Value Field: currentRevenue
• Format: Currency
• Prefix: "$"
• Comparison: previousRevenue

📸 Screenshot Needed: A metric card showing revenue with trend indicator.

7. Data Tables

Display tabular data with sorting and filtering.

Configuration

PropertyDescriptionTitleTable titleData PathPath to array in data (e.g., orders)ColumnsWhich fields to displaySortableAllow column sortingPaginationEnable page navigationPage SizeRows per page

Column Configuration

For each column:

PropertyDescriptionFieldData field nameHeaderDisplay header textWidthColumn widthFormatText, Number, Currency, Date, StatusAlignmentLeft, Center, Right

Example Table Setup

Data:

{
  "recentOrders": [
    {
      "id": "ORD-001",
      "customer": "Acme Corp",
      "total": 1250.0,
      "status": "Shipped"
    },
    {
      "id": "ORD-002",
      "customer": "TechCo",
      "total": 3500.0,
      "status": "Processing"
    },
    {
      "id": "ORD-003",
      "customer": "MegaInc",
      "total": 890.0,
      "status": "Pending"
    }
  ]
}

📸 Screenshot Needed: A data table element on the dashboard showing orders.

8. Screen Parameters

Add interactive filters to your dashboard.

Creating Parameters

1. In the left sidebar, find Screen Parameters
2. Click Add Parameter
3. Configure the parameter:

PropertyDescriptionNameParameter identifier (e.g., startDate)LabelDisplay label (e.g., "Start Date")TypeText, Number, Date, SelectDefaultDefault valueOptionsFor Select type, list of choices

📸 Screenshot Needed: Screen Parameters panel with a date filter configured.

Using Parameters in Scripts

Parameters are passed to your script's context:

function main(context) {
  // Access screen parameters
  const startDate = context.startDate || "2025-01-01";
  const endDate = context.endDate || "2025-12-31";
  const region = context.region || "all";

  // Use in queries
  let query = "SELECT * FROM sales WHERE date >= ? AND date <= ?";
  const params = [startDate, endDate];

  if (region !== "all") {
    query += " AND region = ?";
    params.push(region);
  }

  return tables.query(query, params);
}

Using Parameters in Webhooks

Parameters are appended as query string or body fields based on method.

9. Layout & Styling

Grid System

The dashboard uses a responsive grid:

• 12 columns across the canvas
• Elements snap to grid
• Drag corners to resize
• Drag body to reposition

Element Sizing

SizeGrid ColumnsBest ForSmall2-3Metric cardsMedium4-6Charts, tablesLarge8-12Full-width charts, large tables

Responsive Behavior

Dashboards automatically adjust on smaller screens:

• Elements stack vertically
• Charts scale to fit container
• Tables become scrollable

Styling Options

Each element can be styled:

• Background Color — Card background
• Text Color — Title and label colors
• Border — Border style and color
• Shadow — Elevation effect
• Padding — Internal spacing

10. Best Practices

Dashboard Design

• Focus on key metrics — Don't overcrowd; prioritize important data
• Use consistent styling — Same colors for same types of data
• Group related items — Place related charts/metrics together
• Consider the audience — Executives want KPIs, operators want details

Data Sources

• Cache when possible — Reduce API calls
• Use appropriate refresh rates — Don't refresh more often than data changes
• Handle errors gracefully — Show loading states and error messages
• Test with realistic data — Ensure charts scale with actual data volumes

Performance

• Limit elements — 10-15 elements maximum per dashboard
• Optimize scripts — Efficient queries and minimal processing
• Use pagination — For large data tables
• Consider load time — Test with slow connections

Maintenance

• Document parameters — Explain what each filter does
• Version your scripts — Use Script Engine versioning
• Test after changes — Verify dashboard still works after script updates
• Monitor usage — Check if dashboards are being used

Screenshots Summary

Please capture the following screenshots to complete this documentation:

1. Dashboard Designer main interface - Canvas with element palette
2. Dashboard Settings panel - Name, description, refresh settings
3. Webhook configuration - URL, method, auth type
4. Script Engine configuration - Script dropdown, test button
5. Properties Panel - Chart element configuration
6. Advanced Chart Configuration - JSON editor with preview
7. Metric card example - Card with trend indicator
8. Data table example - Table showing orders
9. Screen Parameters - Date filter configured

For more information on creating scripts for dashboards, see the Script Engine Guide.