ERPNext Scheduler - Implementation

This skill helps you implement scheduled tasks and background jobs. For exact syntax, see erpnext-syntax-scheduler.

Version: v14/v15/v16 compatible

Main Decision: What Are You Trying to Do?

┌─────────────────────────────────────────────────────────────────────┐
│ SCHEDULER DECISION                                                  │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│ Run at fixed intervals or times?                                   │
│ ├── YES → Scheduler Event (hooks.py)                               │
│ │         See: references/workflows.md §1-2                        │
│ │                                                                   │
│ └── NO → Run in response to user action?                           │
│          ├── YES → frappe.enqueue()                                │
│          │         See: references/workflows.md §3-4               │
│          │                                                          │
│          └── NO → Probably neither - reconsider requirements       │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

Scheduler Event vs frappe.enqueue

| Aspect | Scheduler Event | frappe.enqueue | |--------|----------------|----------------| | Triggered by | Time/interval | Code execution | | Defined in | hooks.py | Python code | | Arguments | None (must be parameterless) | Any serializable data | | Use case | Daily cleanup, hourly sync | User-triggered long task | | Restart behavior | Runs on schedule | Lost if worker restarts |

Which Scheduler Event Type?

┌─────────────────────────────────────────────────────────────────────┐
│ SCHEDULER EVENT TYPE                                                │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│ Simple recurring interval?                                         │
│ ├── Every minute    → scheduler_events.cron["* * * * *"]          │
│ ├── Hourly          → scheduler_events.hourly                      │
│ ├── Daily           → scheduler_events.daily                       │
│ ├── Weekly          → scheduler_events.weekly                      │
│ └── Monthly         → scheduler_events.monthly                     │
│                                                                     │
│ Complex schedule (e.g., "weekdays at 9am")?                        │
│ └── scheduler_events.cron["0 9 * * 1-5"]                          │
│                                                                     │
│ Run after every request?                                           │
│ └── scheduler_events.all (use sparingly!)                          │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

Which Queue?

| Queue | Timeout | Use For | |-------|---------|---------| | short | 5 min | Quick operations (<1 min) | | default | 5 min | Standard tasks (1-3 min) | | long | 30 min | Heavy processing (>3 min) |

Rule: Always specify queue explicitly. Default is short.

Quick Start: Basic Scheduled Task

# myapp/tasks.py
import frappe

def daily_cleanup():
    """Daily cleanup task - no parameters allowed"""
    frappe.db.delete("Error Log", {"creation": ("<", frappe.utils.add_days(None, -30))})
    frappe.db.commit()

# hooks.py
scheduler_events = {
    "daily": [
        "myapp.tasks.daily_cleanup"
    ]
}

After editing hooks.py: bench migrate

Quick Start: Background Job

# myapp/api.py
import frappe
from frappe import enqueue

@frappe.whitelist()
def process_documents(doctype, filters):
    enqueue(
        "myapp.tasks.process_batch",
        queue="long",
        timeout=1800,
        job_id=f"process_{doctype}_{frappe.session.user}",  # v15+ dedup
        doctype=doctype,
        filters=filters
    )
    return {"status": "queued"}

Critical Rules

1. Scheduler tasks receive NO arguments

# ❌ WRONG
def my_task(doctype):  # Arguments not supported
    pass

# ✅ CORRECT
def my_task():  # Parameterless
    doctype = "Sales Invoice"  # Hardcode or read from settings

2. ALWAYS migrate after hooks.py changes

bench migrate  # Required to register new scheduler events

3. Jobs run as Administrator

Scheduler and enqueued jobs run with Administrator permissions. Always commit explicitly.

4. Commit after batches, not per record

# ❌ WRONG - Slow
for doc in docs:
    doc.save()
    frappe.db.commit()  # Commit per record

# ✅ CORRECT - Fast
for doc in docs:
    doc.save()
frappe.db.commit()  # Single commit after batch

5. Use job_id for deduplication (v15+)

enqueue(..., job_id="unique_identifier")  # Prevents duplicate jobs

Version Differences

| Aspect | v14 | v15 | v16 | |--------|-----|-----|-----| | Tick interval | 4 min | 60 sec | 60 sec | | Job dedup | job_name | job_id | job_id | | Cron support | ✅ | ✅ | ✅ |

V14 deduplication uses different parameter:

# v14
enqueue(..., job_name="unique_id")
# v15+
enqueue(..., job_id="unique_id")

---

Reference Files

| File | Contents | |------|----------| | workflows.md | Step-by-step implementation patterns | | decision-tree.md | Detailed decision flowcharts | | examples.md | Complete working examples | | anti-patterns.md | Common mistakes to avoid |

---

See Also

• erpnext-syntax-scheduler - Exact syntax reference
• erpnext-errors-serverscripts - Error handling patterns