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 address notified: my_accounting_address@mycompany.ai
• Event: document successfully exported

{
  "actions": [
    {
      "scope": {
        "type": "queue",
        "filter": [
          "3"
        ]
      },
      "trigger": {
        "type": "status_change",
        "params": {
          "filter": "status=exported"
        }
      },
      "template": 1,
      "recipients": {
        "type": "explicit",
        "values": [
          {
            "name": "Accounting",
            "email": "my_accounting_address@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",
        "params": {
          "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 body of the email may contain placeholder parameters such as {document_urls} or {document_count} which will be evaluated when the email is sent.

• 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:

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.
values	list	Only for the explicit type	recipient	List of value objects. They have two keys: name and email
name	string	yes	value	Display the name of the email recipient.
email	string	yes	value	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.
params	object	yes	trigger	Trigger parameters to be evaluated. Contains status_from, status_to, expression, and filter.
status_from	string	no	params	Defined in annotation lifecycle for matching of the initial status.
status_to	string	no	params	Defined in annotation lifecycle for matching of the new status.
expression	string	no	params	Evaluated on fetched annotations.*
filter	string	no	params	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.

* 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.

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.