Document notifications
A document notification posts a message in Raven when something happens to any document from any Frappe app on your site, such as each time a document of a given type is submitted.

An agent sends the message, to a channel, to a person as a direct message, or both. The document card is attached.
Only Raven Admins and System Managers can set up document notifications, in Settings > Document Notifications. Ask one to do it. Each notification needs an agent to send it, so create one first. See Agents.

Create a notification
- Open Settings > Document Notifications and click Create.
- Fill in the Details tab.
- On the Recipients tab, add at least one recipient.
- Click Create.
A condition on the Conditions tab is optional. A new notification is enabled.
Details

| Field | What it does |
|---|---|
| Name | A name for the notification. It can't be changed after you save. |
| Send Alert On | The event that sends the message. See the table below. |
| Document Type | The type of document to watch. |
| Sender | The agent that sends the message. |
| Hide document preview in the notification message | Sends the message without the document card. |
| Message Content | The text of the message. It takes formatting and values from the document. |
| Send Alert On | When the message is sent |
|---|---|
| New Document | When a document is created. |
| Update | Every time a document is saved, including when it is created and when it is submitted. |
| Submit | When a document is submitted. |
| Cancel | When a document is canceled. |
| Delete | When a document is deleted. |
To put a value from the document in the message, write the field name between double braces, like {{ doc.name }}. The list under the message box shows every field of the document type; click a row to copy it. See Write the message.
Recipients
Click Add Recipient for each place the message should go.

| Column | What it does |
|---|---|
| Channel Type | Channel posts in a channel. Direct Message sends a direct message to a person. |
| Variable Type | How Raven finds the channel or person. See the table below. |
| Value | The channel, the person, the field or the Jinja expression. |
| Variable Type | What to put in Value |
|---|---|
| Static | One channel or one person. The message always goes there. |
| Document Field | A field of the document that holds a channel or a user. Fields that link to one are listed under Suggested. For direct messages, Owner and Modified By are also suggested. |
| Jinja | An expression that gives the ID of a channel or the email of a user, such as {{ doc.owner }}. |
A person needs the Raven User role 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 for every document that matches the event.

Write a Python expression that uses doc. The message is sent only when it is true. The list under the condition shows the fields of the document type. See Write the condition.
Write the message
Message Content is a Jinja template, the template language Frappe uses. Raven fills it in when the event happens. It can use these names:
| Name | What it is |
|---|---|
doc |
The document that changed, with all its fields. For Delete, the document as it was before it was deleted. |
frappe |
Frappe's read-only helpers, such as frappe.utils, frappe.db.get_value and frappe.get_fullname. |
nowdate |
A function that gives today's date. |
The helpers can only read data. A template can't change or create documents.
| Expression | Gives |
|---|---|
{{ doc.name }} |
The ID of the document. |
{{ doc.doctype }} |
The document type. |
{{ frappe.get_fullname(doc.owner) }} |
The full name of the person who created the document. |
{{ frappe.get_fullname(doc.modified_by) }} |
The full name of the person who last changed it. |
{{ frappe.utils.format_date(doc.modified) }} |
The date it was last changed, in the site's date format. |
{{ frappe.utils.today() }} |
Today's date. |
{{ frappe.db.get_value("User", doc.owner, "email") }} |
A value read from another document. |
Use doc.get("fieldname") for a field that might be empty or missing. It gives nothing instead of an error.
Each line in Message Content becomes a line in the message. Here 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:
Rows in {{ doc.name }}:
{% for row in doc.get("items", []) %}
{{ row.idx }}. {{ row.get("item_name") }}
{% endfor %}
Write the condition
The condition is one Python expression, without double braces. It can use the same names as the message: doc, frappe and nowdate. The message is sent when the expression gives a value that is true, or not empty. Each line below is a separate example:
# 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 notification posts in a channel and sends a direct message to the person who made the document, each time a document is submitted.
- Open Settings > Document Notifications and click Create.
- In Name, enter
Submitted documents. - In Send Alert On, pick Submit.
- In Document Type, pick the type of document.
- In Sender, pick an agent.
- In Message Content, enter
{{ doc.name }} was submitted. - On the Recipients tab, click Add Recipient. Leave Channel and Static, and pick the channel under Value.
- Click Add Recipient again. Pick Direct Message and Document Field, then pick Owner under Value.
- Click Create.
The next time someone submits a document of that type, the agent posts in the channel and sends the message to the document's owner, with the document card attached to both.
Change, disable or delete a notification
Click a notification in the list, make your changes and click Save. To stop it without deleting it, click ⋮ at the top right and then Disable; Enable turns it back on. Delete in the same menu removes it for good.