Document notifications

A document notification posts a message in Raven when something happens to a document. For example, it can tell a channel each time a document of a given type is submitted. It works with any document from any Frappe app on your site.

The message is sent by an agent. It can go to a channel, to a person as a direct message, or both. The document card is attached to the message.

See your notifications

Open Settings and click Document Notifications. The list shows each notification, its document type, when it is sent and whether it is enabled.

Create a notification

1. Open Settings and click Document Notifications.
2. Click Create.
3. Fill in the Details tab.
4. Click the Recipients tab and add at least one recipient.
5. If you want, click the Conditions tab and add a condition.
6. Click Create.

A new notification is enabled. The sections below explain each field.

Details

To put a value from the document in the message, write the field name between double braces, like {{ doc.name }}. Under the message box, Raven lists every field of the document type you picked. Click a row to copy it. See Write the message for more.

Recipients

Click Add Recipient to add a row. Add one row for each place the message should go.

A person must be a Raven user to get a direct message. The agent posts in the channel even if it is not a member.

Conditions

A condition limits which documents send the message. Leave it empty to send the message for every document that matches the event.

Write a Python expression that uses doc. The message is sent only when the expression is true. Under the condition, Raven lists the fields of the document type. Click a row to copy it. See Write the condition for examples.

Write the message

The message is a Jinja template, the template language Frappe uses. Type it in Message Content. Raven fills it in when the event happens, then sends it.

The template can use these names:

The helpers can only read data. A template can't change or create documents.

Some useful expressions:

Use doc.get("fieldname") for a field that might be empty or missing. It gives nothing instead of an error.

Each line you type in Message Content becomes a line in the message. In this template, the second line is empty when the document has no status:

{{ doc.doctype }} {{ doc.name }} was submitted by {{ frappe.get_fullname(doc.modified_by) }}.
{% if doc.get("status") %}Status: {{ doc.status }}{% endif %}
Submitted on {{ frappe.utils.format_date(doc.modified) }}.

To list the rows of a table field, loop over it. Replace items with the name of the table field in your document type:

Rows in {{ doc.name }}:
{% for row in doc.get("items", []) %}
{{ row.idx }}. {{ row.get("item_name") }}
{% endfor %}

You can format the text around the template tags with the toolbar, such as bold or a list.

Write the condition

The condition is one Python expression. Each line in the block below is a separate example. It can use the same names as the message: doc, frappe and nowdate. Leave out the double braces. The message is sent when the expression gives a value that is true, or not empty.

# Only documents with this status
doc.status == "Open"

# One of several statuses
doc.status in ("Open", "Replied")

# Only submitted documents
doc.docstatus == 1

# A number above a limit
doc.get("grand_total", 0) > 10000

# A field that is filled in
doc.get("assigned_to")

# Not created by the Administrator
doc.owner != "Administrator"

The fields in these examples are only examples. Use the fields of your document type, from the list under the condition.

A full example

This example posts in a channel and sends a direct message to the person who made the document, each time a document is submitted.

1. Open Settings and click Document Notifications, then click Create.
2. In Name, enter Submitted documents.
3. In Send Alert On, pick Submit.
4. In Document Type, pick the type of document.
5. In Sender, pick an agent.
6. In Message Content, enter {{ doc.name }} was submitted.
7. Click the Recipients tab, then click Add Recipient.
8. Leave Channel and Static, and pick the channel under Value.
9. Click Add Recipient again.
10. Pick Direct Message and Document Field, then pick Owner under Value.
11. Click Create.

The next time someone submits a document of that type, the agent posts the message in the channel and sends it to the document's owner. The document card is attached to both.

Change, turn off or delete a notification

Click a notification in the list to open it. Make your changes and click Save.

To stop a notification without deleting it, click ⋮ at the top right and click Disable. Click Enable to turn it back on. To remove it for good, click ⋮ and then Delete.