Server Script

A Server Script lets you dynamically define a Python Script that is executed on the server on a document event or API

Introduced in Version 12

1. How to create a Server Script

To create a Server Script

  1. If your site is being hosted on, contact support to activate Server Script. In case of self-hosted accounts, set server_script_enabled as true in site_config.json of your site.
  2. To add/edit Server Script, ensure your role is System Manager.
  3. Type "New Server Script" in the awesomebar and hit enter to create a new Server Script document.
  4. Set the type of server script (Document Event / API).
  5. Set the document type and event name, or method name, script and save.

2. Features

2.1 Enabling Server Script

Server script must be enabled via site_config.json

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

2.2 Document Events

For scripts that are to be called via document events, you must set the Reference Document Type and Event Name to define the trigger

  • Before 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

You can create a new API that can be accessed via api/method/[methodname] by the script type "API"

If you want the guest user to access the API, you must check on "Allow Guest"

The response can be set via frappe.response["message"] object

2.3 Security

Frappe Framework uses the RestrictedPython library to restrict access to methods available for server scripts. Only the safe methods, listed below are available in server scripts

For allowed methods, see Script API

2.4 Using Server Scripts as libraries

You can use a server script as an internal method by setting frappe.flags value in script.

3. Examples

3.1 Change the value of a property before change

Script Type: Before Save

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

3.2 Custom validation

Script Type: "Before Save"

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

3.3. Auto Create To Do

Script Type: "After Save"

if doc.allocted_to:
        doctype = 'ToDo'
        owner = doc.allocated_to,
        description = doc.subject

3.4 API

  • Script Type: API
  • Method Name: test_method
frappe.response['message'] = "hello"

Request: /api/method/test_method

3.5 Internal Library

New in version 13

Call one (script_1 script from another script_2)

Script 1:

frappe.flags.my_key = 'my value'

Script 2:

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