What is Script API in Frappe?
The Script API in Frappe v15 is a collection of built-in methods and utilities available for use in:
- Client Scripts (JavaScript)
- Server Scripts (Python)
It provides a standardized way to:
- Access database records
- Manipulate DocTypes
- Trigger UI or backend actions
- Interact with Frappe framework services
It ensures safe, structured, and consistent scripting across ERPNext.
Why Use Script API in ERPNext?
Script API enables developers to extend functionality without modifying core code.
Key Benefits:
- Unified API across client and server
- Simplifies data operations
- Reduces custom code complexity
- Maintains upgrade compatibility
Where is Script API Used?
Script API is used in:
- Client Scripts → UI logic (JavaScript)
- Server Scripts → Backend logic (Python)
- Custom Apps → Advanced development
What Are Core Script API Categories?
Frappe Script API can be grouped into major functional areas.
1. Document API (ORM)
Used to interact with DocTypes.
Example: Get Document
doc = frappe.get_doc('Customer', 'CUST-0001')
Example: Create Document
doc = frappe.get_doc({
'doctype': 'Customer',
'customer_name': 'Test Customer'
})
doc.insert()
2. Database API
Direct database operations using Frappe abstraction.
Example:
frappe.db.get_value('Customer', 'CUST-0001', 'customer_name')
Example: Check Record Exists
frappe.db.exists('Customer', {'email_id': 'test@example.com'})
3. Utility Functions
General-purpose helper methods.
Example:
frappe.utils.now()
4. Messaging API
Used to communicate with users.
Example:
frappe.msgprint("Operation Successful")
5. Error Handling API
Raise controlled exceptions.
frappe.throw("Invalid Data")
How to Use Script API in Client Script?
Client Scripts use JavaScript-based APIs exposed via frappe.
Example:
frappe.ui.form.on('Sales Order', {
refresh: function(frm) {
frappe.msgprint('Form Loaded');
}
});
How to Use Script API in Server Script?
Server Scripts use Python-based Frappe APIs.
Example:
if not doc.customer:
frappe.throw("Customer is mandatory")
Commonly Used Script API Methods
| Method | Description |
| frappe.get_doc() | Fetch or create document |
| frappe.get_all() | Retrieve multiple records |
| frappe.db.get_value() | Fetch single field value |
| frappe.db.exists() | Check if record exists |
| frappe.msgprint() | Show message to user |
| frappe.throw() | Raise exception |
| frappe.call() | Call server method (client side) |
Real-World Example: Data Validation Flow
if doc.amount <= 0:
frappe.throw("Amount must be greater than zero")
Security & Execution Context
Frappe Script API in v15 ensures:
- Controlled database access
- Restricted execution (especially in Server Scripts)
- Role-based permission enforcement
Prevents unauthorized operations and ensures system safety.
Best Practices for Using Script API
- Use ORM (frappe.get_doc) instead of raw SQL
- Validate inputs before processing
- Avoid unnecessary database calls
- Keep scripts modular and readable
- Handle errors gracefully
Troubleshooting Common Issues
Issue: Method Not Found
- Ensure correct API name
- Verify spelling and syntax
Issue: Permission Denied
- Check user roles and permissions
Issue: Data Not Updating
- Ensure .save() or .insert() is called
Integration Patterns
Script API integrates with:
- DocType Events → Automation
- REST API → External integrations
- Workflows → Business processes
- Scheduler Jobs → Background execution
Target Audience
- ERPNext Developers
- Frappe Developers
- Backend Engineers
- Technical Consultants
Technical Prerequisites
- Python and JavaScript knowledge
- Understanding of DocTypes
- Familiarity with Frappe framework
Industry Relevance
Script API is essential across:
- Manufacturing ERP
- Financial Systems
- CRM automation
- Inventory management
Official References
Frappe Script API Docs:
https://docs.frappe.io/framework/user/en/desk/scripting/script-api
Frappe GitHub v15:
