Raven

Raven

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.

A message from a document notification

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.

The list of document notifications

Create a notification

  1. Open Settings > Document Notifications and click Create.
  2. Fill in the Details tab.
  3. On the Recipients tab, add at least one recipient.
  4. Click Create.

A condition on the Conditions tab is optional. A new notification is enabled.

Details

The Details tab of a document notification

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.

The Recipients tab of a document notification

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.

The Conditions tab of a document notification

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.

  1. Open Settings > Document Notifications and 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. On the Recipients tab, click Add Recipient. Leave Channel and Static, and pick the channel under Value.
  8. Click Add Recipient again. Pick Direct Message and Document Field, then pick Owner under Value.
  9. 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.

Last updated 2 weeks ago
Was this helpful?
Thanks!