Script Report

Script Reports are used when the required report cannot be created using Report Builder or Query Reports. They are built using Python scripts, providing complete flexibility for implementing complex business logic, custom calculations, and advanced data retrieval.

Note:

Since Script Reports provide unrestricted access to Python, they can only be created by System Managers/Administrators during development and are typically included as part of a custom application.

Tip:

You must enable Developer Mode before creating a standard Script Report.

How to Create a Script Report

To create a Script Report, search for New Report using the Awesome Bar and create a new report with the appropriate settings.

Set Report Type to Script Report.
Enable Is Standard.
Select the module where the report should be created.
Open the generated report folder inside your application (for example, erpnext/accounts/report/<report-name>).
Write the report logic in the generated {report-name}.py file.
Define report filters in the {report-name}.js file.

Creating a standard Script Report automatically generates the required Python and JavaScript template files.

Standard and Custom Script Reports

Available from Version 12

Starting with Version 12, Frappe Framework supports both Standard and Custom Script Reports.

Standard Script Reports

Stored as files inside the application.
Written using Python and JavaScript.
Best suited for reports distributed with custom apps.

Custom Script Reports

Created directly from the Report document.
The Python script is written inside the Code section.
Supports the Frappe Script API.

Choose Standard Reports for app development and Custom Reports for report customization within a site.

Columns and Filters

Available from Version 13

Version 13 introduced the ability to configure report columns and filters directly from the Report document.

For each column or filter, you can configure:

Label
Width
Field Type
Additional field properties

Filter values can also be referenced inside queries using formatting variables.

%(customer)s

Tip:

Using predefined filters makes reports reusable without modifying the underlying script.

Writing the Report Script

Custom Script Report

Custom reports allow you to write Python code directly inside the Report document using the Frappe Script API.

return frappe.db.get_all(
    "User",
    ["first_name", "last_name"],
    filters=filters
)

Standard Script Report

A standard Script Report contains an execute() function that accepts report filters and returns the report output.

from __future__ import unicode_literals

def execute(filters=None):
    columns = []
    data = []
    return columns, data

The execute() function normally returns the report columns and data, but it can also return additional information such as charts and summaries.

Values Returned by execute()

1. Columns

Columns define the structure of the report table, including field names, labels, data types, and options.

Note:

You only need to return columns from the script if they have not already been configured in the Report document.

2. Results (Data)

The data returned by the report can be either:

A list of dictionaries
A list of lists

Each row represents one record displayed in the report table.

3. Chart

Returns the configuration for the chart displayed at the top of the report.

4. Report Summary

Displays important metrics or KPIs above the report table using summary cards.

[{
    "value": profit,
    "indicator": "Green" if profit > 0 else "Red",
    "label": _("Total Profit This Year"),
    "datatype": "Currency",
    "currency": "INR"
}]

When returning multiple values from execute(), they must be returned in the expected order defined by the framework.

Adding Report Filters

Filters are defined in the report’s {report-name}.js file. The selected filter values are automatically passed to the execute() function as a dictionary.

Typical filter definitions include:

Field Name
Label
Field Type
Options
Default Value
Visibility Conditions

Conditional Filters

Version 13 introduced support for the depends_on property in Script Report filters.

This property controls whether a filter is displayed based on the value of another field or a custom expression.

Tip:

Use depends_on to display filters only when they are relevant, making reports easier to use.

Navigating to Reports

You can quickly open any Report by typing its name into the Awesome Bar and pressing Enter.

Snapshot Reports

Snapshot Reports are an advanced reporting engine designed for analytical workloads. They require reports to be rewritten to use OLAP databases, making them suitable for large-scale reporting and business intelligence scenarios.

Snapshot Reports are intended for advanced reporting requirements and require additional implementation compared to standard reports.

Rating: 0 / 5 (0 votes)