Unlocking Business Efficiency with Empress Server Scripts

Guides & Tutorials
1

Introduction

In this guide, we will explore Server Scripts in Empress. This feature offers a powerful way to define scripts that run on the server during document events or API calls. It’s like having your own mini-programmer working behind the scenes to streamline your business operations.

How to Create a Server Script

Here’s how you can create your own server script:

  1. If your site is on empress.eco, contact our support team to enable the Server Script feature. For self-hosted sites, simply set server_script_enabled to true in your site’s configuration settings.
  2. To add or adjust a server script, you’ll need to be a System Manager.
  3. Click on “New Server Script” in your toolbar to start creating a new script.
  4. Choose the type of script you want to create: Document Event, API, or Permission Query.
  5. Define the document type and event name, or the method name, then write your script and save it.

Dive into the Features of Server Scripts

Let’s unpack the core features of Server Scripts and see how they can enhance your business processes.

Activating Server Scripts

Before you can use server scripts, they need to be activated. This can be done through your site’s configuration settings.

Utilizing Document Events

You can call scripts via document events. Just define a Reference Document Type and Event Name to set the trigger. Your script could be triggered by a wide range of events, such as before saving a document, after submitting a document, or even before deleting a document.

Exploring API Scripts

You can create a new API that’s accessible via api/method/[methodname] by choosing the script type “API”. If you want to allow guest users to access the API, simply check the “Allow Guest” box. You can set the response using the empress.response["message"] object.

Understanding Permission Query

This script type lets you add custom conditions to refine the results shown in your document lists. For example, if you want to show a list of tasks to a user only if they are assigned to them or were assigned by them, you can use this script type.

Maintaining Security

To ensure the security of your data, Empress uses the RestrictedPython library to limit access to the methods available for server scripts. Only safe methods are available in server scripts.

Server Scripts in Action

Here are some practical examples of server scripts:

Modifying a Property Before Change

Set the script type to “Before Save” to change the value of a property before it changes.

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

Implementing Custom Validation

Set the script type to “Before Save” to add a custom validation.

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

Automatically Creating To Do Lists

Set the script type to “After Save” to automatically create a to-do list.

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

Creating an API

Set the script type to API and enter test_method as the method name.

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

To make a request, use: /api/method/test_method.

In conclusion, Server Scripts empower you to automate and streamline your business operations, making your Empress experience even more efficient and effective. For further assistance or more detailed information, reach out to our support team or refer to our comprehensive non-technical resources.