Developing Customized Script Reports in Empress

Developers
1

Introduction

Welcome, developers! One of the powerful features of Empress is the ability to create Script Reports, a tool that provides a way to generate customized reports using Python scripts. This guide will guide you through the in-depth nuances of creating, modifying, and debugging Script Reports.

Why Script Reports Matter

Script Reports offer unrestricted access via Python scripts, enabling developers to create highly tailored reports that cater to specific business needs. They are a powerful tool for administrators and developers, and can provide insights that may not be achievable using the built-in Report Builder or Query Report.

Note: To create Script Reports, you must enable Developer Mode.

Creating a Script Report

  1. Type “new report” in the awesomebar and hit enter.
  2. Set Report Type as “Script Report”.
  3. Set “Is Standard” as “Yes”.
  4. Select the Module in which you want to add this report.
  5. In the module folder (e.g., erpnext/accounts/report/[report-name] for Accounts in ERPnext), templates for the report files will be created.
  6. Write your Python script in the generated {report-name}.py file.
  7. Add filters to your report by adding them to {report-name}.js.

Standard and Custom Reports

Starting from Version 12, you can create custom Query and Script reports in Empress. In custom reports, the script can be added directly in the Report itself, and you can utilize the Script API functions of Empress.

Configuring Columns and Filters

From Version 13 onwards, you can configure columns and filters in the Report document. Here, you can set the label, width, format (fieldtype) for the columns and filters. Filters can be used as formatting variables in the query— for example, a filter of type customer can be used as %(customer)s in the query.

Writing the Script

Custom Report

In custom reports, you can utilize the Script API and write the script directly in the Code section:

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

Standard Report

The generated .py file comes with a boilerplate for your report. The execute function, which takes filters and returns columns and data, will look like this:

from __future__ import unicode_literals

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

The execute function should return the columns and the data to be shown in the report by default. Additional parameters such as message, chart, report_summary, skip_total_rows can be returned by the execute function.

Adding Filters

To add filters to your report, define the fields and their fieldtypes in the {report-name}.js file. The filter values will be available in the execute method as a dict.

Just like the depends_on property that controls the display of fields, as of Version 13, we have introduced depends_on for Script Report filters. This can be used to determine whether the filter will be visible based on the value of the condition in depends_on.

Conclusion

Script Reports offer a high degree of customization and flexibility, enabling developers to create highly tailored reports. This feature is crucial for providing in-depth insights that can drive business decision-making. By understanding and effectively utilizing Script Reports, developers can further enhance the capabilities of Empress, creating sophisticated, tailored business solutions.