Using Custom Methods to Trigger Notifications

In Frappe, the Notification feature allows users to configure automated alerts based on various events and conditions. One of the most flexible options is using the "Send Alert On" method with a custom "Trigger Method." This approach allows you to trigger notifications programmatically from your code.

Step 1: Create the Notification

1. Navigate to the Notification List: In your instance, go to the Notification doctype via the search bar or by navigating through the Settings module.

2. Set Notification Details: Create a new notification with the following key fields:

   • Document Type: Select the DocType for which the notification will be triggered.
   • Subject: Define the email subject or notification title.
   • Message: Compose the content of the notification. You can use Jinja templating to dynamically include values from the document (e.g., {{ doc.name }}).
   • Send Alert On: Select Method from the dropdown.

3. Specify the Trigger Method: In the "Trigger Method" field, enter the custom method name (e.g., notify_delayed_sales_order). This is the name you will use to programmatically trigger the notification. Note that this method name does not need to exist in the codebase. It simply serves as an identifier for when you programmatically trigger the notification using the doc.run_trigger() method.

4. Set Recipients: Specify the recipients using the available options (e.g., Role, Email, or Owner).

5. Save the Notification: Save your changes.

Step 2: Programmatically Trigger the Notification

To trigger the notification in your code, you will use the doc.run_trigger("notify_delayed_sales_order") method. Here, doc refers to an instance of the DocType you selected in the Notification.

Example Code

Below is an example of how to trigger a notification when a Sales Order is delayed beyond the promised delivery date.

import frappe
from frappe.utils import today

def notify_delayed_sales_orders():
    delayed_orders = frappe.get_all(
        "Sales Order",
        filters={
            "status": "To Deliver and Bill",
            "delivery_date": ["<", today()],
        },
        fields=["name", "customer", "delivery_date"]
    )

    for order in delayed_orders:
        doc = frappe.get_doc("Sales Order", order.name)
        doc.run_trigger("notify_delayed_sales_order")

    frappe.db.commit()
    return f"{len(delayed_orders)} delayed orders processed."

Step 3: Testing the Notification

1. Test Your Code: Call the function containing doc.run_trigger() in a script, API, or custom action to test the notification. For example:

   notify_delayed_sales_orders()
   

2. Verify the Notification: Check your email inbox or the notification center in the instance to confirm that the notification is received.

Step 4: Debugging Issues

If the notification is not triggered as expected, consider the following:

• Ensure the custom method name in the Notification matches the method name in your code.
• Verify that the doc.run_trigger() method is being executed by checking the server logs or adding debug statements.
• Check the notification logs in ERPNext via Email Queue or the Error Log.

Benefits of Method-Based Triggering

1. Flexibility: Trigger notifications conditionally based on custom business logic.
2. Reusability: Centralize notification logic, making it easy to update and maintain.
3. Scalability: Integrate notifications seamlessly with custom workflows or automated processes.