How to Build Dashboards in ERPNext (Step-by-Step Guide)

Introduction

Dashboards in ERPNext help businesses visualize their key metrics using charts, KPIs, reports, and custom data sources. This blog explains how dashboards work internally, how to create dashboard charts, how to link them to a workspace, and how to customize them using scripts, queries, and API calls.

1. Understanding ERPNext Dashboard Architecture

This section introduces the internal structure of ERPNext dashboards. It explains how different components like Dashboard Chart, Dashboard, and Workspace work together to display business metrics visually.

ERPNext dashboards are built using three main components:

Workflow internally:

Data Source → Dashboard Chart → Dashboard → Workspace Display

2. Workflow Diagram: How Dashboards Work in ERPNext

This part explains the flow of how data moves through different dashboard components.

3. Creating a Dashboard Chart (Step-by-Step)

This section provides a detailed guide to creating a new Dashboard Chart, selecting document types, chart types, filters, and data sources.

Steps:

1. Go to: Dashboard Chart → New
2. Enter the chart name (Ex: Monthly Sales Trend).
3. Choose the Document Type (Ex: Sales Invoice).
4. Select Chart Type: Bar, Line, Pie, KPI, Donut, Heatmap
5. Choose the Data Source: Report-based or Custom Query
6. Apply filters
7. Save and Refresh

4. Table: Common Chart Types & Their Use Cases

This table explains what each chart type is best used for.

5. Adding a Chart to a Dashboard

This section guides you on placing a chart inside a dashboard layout.

Steps:

1. Go to Dashboard → New
2. Enter Dashboard Name
3. Add Row under Cards
4. Select the chart
5. Arrange charts
6. Save

6. Adding Dashboard to Workspace

This shows how to display the dashboard on ERPNext’s workspace.

Steps:

1. Go to Workspace
2. Click Edit
3. Add Dashboard
4. Select your dashboard
5. Save

7. Creating Custom Dashboard Chart Using Script Report

Use Python to create advanced datasets for charts.

def execute(filters=None):
    data = frappe.db.sql("""
        SELECT
            MONTH(posting_date) as month,
            SUM(base_grand_total) as total
        FROM `tabSales Invoice`
        WHERE docstatus = 1
        GROUP BY month
    """, as_dict=True)

    columns = [
        {"label": "Month", "fieldname": "month", "type": "Int"},
        {"label": "Total Amount", "fieldname": "total", "type": "Currency"}
    ]

    return columns, data

8. Creating Dashboard Chart with Custom Query

SELECT 
    posting_date, 
    SUM(base_net_total) AS total 
FROM `tabSales Invoice` 
WHERE docstatus = 1 
GROUP BY posting_date

9. Using Filters & Dynamic Date Ranges

10. Custom Dashboard Chart Using frappe.call()

frappe.call({
    method: "my_app.api.get_sales_data",
    callback: function(r) {
        // handle chart render
    }
});

11. Adding Custom HTML Block

<div class="custom-metric">
   <h3>Total Orders Today</h3>
   <span>{{ total_orders }}</span>
</div>

12. Dashboard Permissions

13. KPI Dashboard Creation

SELECT SUM(paid_amount) FROM `tabPayment Entry` WHERE docstatus=1

14. Real-Time Dashboard Refreshing

15. Creating Heatmap Dashboard

1. Add Heatmap chart
2. DocType: Activity Log
3. Group By creation date
4. Save

16. Custom Python API Feed

@frappe.whitelist()
def custom_sales():
    return frappe.db.get_list('Sales Order', fields=['transaction_date','grand_total'])

17. Mobile Dashboard Optimization

• Fewer charts per row
• Use KPIs
• Avoid big tables

18. Troubleshooting Dashboard Issues

19. Best Practices

• Max 6 charts per dashboard
• Consistent colors
• KPIs on top
• Use filters
• Use Script Reports for complex logic

20. Complete Dashboard Workflow Summary

Create Report → Define Chart → Add to Dashboard → Add to Workspace → Publish

Conclusion

Dashboards in ERPNext offer a powerful way to visualize business data with charts, KPIs, reports, and custom logic. Using script reports, SQL queries, and workspace customization, you can build fully personalized, dynamic dashboards tailored to any department.