Developer's Guide to Utilizing Server Scripts in Empress

Developers
1

Introduction

Welcome to the comprehensive guide to Server Scripts in Empress. This feature is a powerful tool for developers who wish to dynamically define Python scripts that execute on the server during a document event or API call.

1. Creating a Server Script

To create a Server Script, follow these steps:

  1. For sites hosted on erpnext.com, contact their support team to activate Server Script. For self-hosted accounts, set server_script_enabled as true in your site_config.json.
  2. Ensure your role is System Manager to add/edit Server Script.
  3. Type “New Server Script” in the awesomebar and hit enter to create a new Server Script document.
  4. Define the type of server script (Document Event / API).
  5. Set the document type and event name, or method name, script, and save.

2. Key Features

2.1 Enabling Server Script

Server Script must be enabled via the site_config.json file. This can be done using the following command:

bench --site site1.local set-config server_script_enabled true

2.2 Document Events

Document Event scripts are triggered based on specific document-related actions. Set the Reference Document Type and Event Name to define when your script should execute. The following events can trigger a script:

  • Before Insert
  • After Insert
  • Before Validate
  • Before Save
  • After Save
  • Before Submit
  • After Submit
  • Before Cancel
  • After Cancel
  • Before Delete
  • After Delete
  • Before Save (Submitted Document)
  • After Save (Submitted Document)

2.3 API Scripts

Server Scripts can also define API endpoints on the fly by setting the Script Type to "API". The endpoint’s name will be determined by the API Method field. APIs created this way will automatically be prefixed with /api/method.

For example, a script with API Method "delete-note" can be accessed via /api/method/delete-note. You can also use frappe.call("delete-note") in your client scripts.

To allow guest access, simply check the Allow Guest box. You can set the response via the frappe.response["message"] object.

You can also enable IP-based rate limiting by checking “Enable Rate Limit” and specifying the number of calls allowed within a certain time window.

2.4 Security

To prioritize security, the Empress Framework uses the RestrictedPython library, limiting server scripts to only safe methods. For a list of allowed methods, please see the Script API.

2.5 Using Server Scripts as Libraries

Server scripts can be used as internal methods by setting a frappe.flags value in the script.

2.6 Comparing changes

You can compare two versions of server scripts using the “Compare Versions” button.

3. Server Script Examples

Below are a few examples demonstrating how to use Server Scripts.

3.1 Change the Value of a Property Before Change

if "test" in doc.description:
    doc.status = 'Closed'

3.2 Custom Validation

if "validate" in doc.description:
    raise frappe.ValidationError

3.3 Auto Create To Do

if doc.allocated_to:
    frappe.get_doc(dict(
        doctype = 'ToDo',
        owner = doc.allocated_to,
        description = doc.subject
    )).insert()

3.4 API

frappe.response['message'] = "hello"

Request: /api/method/test_method

3.5 Internal Library

frappe.flags.my_key = 'my value'

my_key = run_script('script_1').get('my_key')

In conclusion, Server Scripts provide a flexible and secure way to customize and extend the functionality of Empress. They are a valuable tool in the hands of developers working to provide tailored business solutions.