Email Notifications Extension

From this article you will learn:

What is the Email Notifications extension
What are the common use cases
How to set up the Email Notification extension
What are the available configuration parameters

What is the Email Notifications extension?

Email Notifications Extension can send email notifications at annotation status change which helps you keep track of new documents or undesired transitions such as failure to export the document.

Another possibility is a periodic evaluation email-sending trigger. You can use it as a reminder of forgotten documents waiting for your action. This function can send emails with fully customizable templates that allow placeholder values, such as links to the triggering documents.

Common use case configurations for Email Notifications extension

Below are setup examples you can copy and modify for easy setup.

Email notification on the successful export of a document

In this example, we want to get notified of any document successfully exported from queue 3. The function will send an email template 1 to the my_accounting_address@my_company.ai email address.

Example:

Affected queue: 3
Email template used: 1
Email addresses notified: my_accounting_address@mycompany.ai, someone_else@mycompany.ai
Event: document successfully exported

{
  "actions": [
    {
      "scope": {
        "type": "queue",
        "filter": [
          "3"
        ]
      },
      "trigger": {
        "type": "status_change",
        "status_to": "exported"        
      },
      "template": 1,
      "recipients": {
        "type": "explicit",
        "to": [
          {
            "name": "Accounting",
            "email": "my_accounting_address@mycompany.ai"
          }
        ],
        "cc": [
          {
            "name": "Someone Else",
            "email": "someone_else@mycompany.ai"
          }
        ]
      }
    }
  ]
}

Periodic notification for documents waiting to review

In this example, the trigger is evaluated periodically on a given expression. We use an expression to filter documents that are in to_review status. Additionally next part of the expression filters emails that arrived in the last 30 days. You may define multiple conditions with the & operator in the scope object. There is also the definition of threshold, which sets the minimum number of documents for triggering a notification to 20.

Example:

Affected queue: 4
Email template used: 2
Notification threshold: 20
Email address notified: All email addresses assigned to the queue
Evaluated expression: status=to_review&arrived_at_before={date.today() + timedelta(days=30)}&arrived_at_after={date.today() – timedelta(days=30)}
Recipients: emails associated with the queue

{
  "actions": [
    {
      "recipients": {
        "type": "queue"
      },
      "trigger": {
        "type": "expression",
        "filter": "status=to_review&arrived_at_before={date.today() + timedelta(days=30)}&arrived_at_after={date.today() - timedelta(days=30)}",
      },
      "scope": {
        "type": "queue",
        "threshold": 20,
        "filter": [
          "4"
        ],
      },
      "template": 2
    }
  ]
}

How to set up the Email Notification extension

Setting up the extension itself takes a few simple steps.

Step 1: Prepare your queues and email templates

The first step is to identify the queue(s) with the documents that require this function.

Then you need to create email templates:

Click Queue Configuration > Emails > Smart email automation > Create a new template.
Define the Name, Subject, and Message of the email.
Click Save.

The email template may contain placeholder parameters. In addition to the built-in template placeholders, you can also use additional values that are available only for this extension:

{{document_urls}}: an unformatted list of document URLs that correspond to the action filters.

{{document_count}}: the total count of documents that have been matched by the action filters.

{{queue_url}}: the URL of the outgoing queue.

{{queue_name}}: the name of the outgoing queue.

{{current_timestamp}}: the current timestamp, provided in the format “%Y-%m-%d %H:%M:%S”.

Get the ID of the template you have just created from the edit template view:

Step 2: Activate Email Notifications in the Rossum Store

To enable Email Notifications, go to the Rossum application and:

Click on the Extensions tab at the top of the app
Click on the Rossum store option to display all the available extensions
Select the “Email Notifications” extension tile
Click “Try extension”

Step 3: Specify to which queue(s) you want to add this extension.

In the “Rossum Store Extension Settings,” scroll down to “Queues” and select the queue(s) in which you want to use the function. Please remember to save your changes once you’ve chosen the desired queues.

Step 4: Set up email notifications

You can set up the Email Notification function using the configuration field in the UI or the settings attribute of the hook API object. First, you need to set up trigger events. Relevant events are:

Document status - Changed : triggered whenever a document changes status
Invocation - Scheduled : periodically evaluated for relevant documents

Next, go to the configuration. It is in JSON format. It consists of a list of actions that should be evaluated to trigger the email. Additionally, the function requires access to Rossum API, so set yourself up as a token owner.

Complete list of available parameters:

* All schema IDs used on the expression (except for params on the timedelta Object) must be of type date (Rossum schema field type). If a metadata field is used in the expression, the extension will parse only its date part and use it for the calculation.

Attribute	Type	Required	Parent	Description
actions	list	yes	–	List action definitions containing `recipients`, `trigger`, `scope`, and `template`.
recipients	list	yes	action	List of an object defining recipients to be notified. Contains `type` and `values`.
type	string	yes	recipient	Possible values are `queue`, which uses all email addresses associated with the queue, or `explicit`.
to	list	yes (only for the explicit type)	recipient	List of “to” recipient objects. They have two keys: `name` and `email`.
cc	list	no (only for the explicit type)	recipient	List of “cc” recipient objects. They have two keys: `name` and `email`.
bcc	list	no (only for the explicit type)	recipient	List of “bcc” recipient objects. They have two keys: `name` and `email`.
name	string	yes	to/cc/bcc	Display the name of the email recipient.
email	string	yes	to/cc/bcc	Email address
trigger	object	yes	action	Trigger object containing `type` and `params`.
type	string	yes	trigger	Possible values are `status_change`, for document status change events or `expression`, for the scheduled ones.
status_from	string	no	trigger	Defined in annotation lifecycle for matching of the initial status.
status_to	string	no	trigger	Defined in annotation lifecycle for matching of the new status.
expression	string	no	trigger	Evaluated on fetched annotations.*
filter	string	no	trigger	Query filter to limit fetched annotations. Applied in Elis API.
scope	object	yes	action	Evaluation scope. Contains `type`, `threshold`, `filter`, and `outgoing_queue`.
type	string	yes	scope	Type of scope. Possible values are `document` or `queue`.
threshold	int	no	scope	A minimal number of positively matched documents to send notification.
filter	list	no	scope	List of strings of filtered queue ids or document ids. Depends on the scope type.
outgoing_queue	string	no	scope	The ID of the outgoing email queue.
template	int	yes	action	The ID of the email template created in Rossum.

It is possible to define the parameter of the timedelta object using the schema_id. The user can decide to use an integer value. If you use an incompatible value, the function will fail.

The expression supports the use of the today() method to get the current date.

If you encounter any problems, contact us at support@rossum.ai.