Skip to content

Notifications

The word "notifications" may refer to two different (but related) things:

  1. In tucana's studio, it refers to the email templates editing section.
  2. In laputa's codebase, the notification system is a generic way to trigger some action (e.g send an email to some people) when some event occurs. These emails use the email templates described above.

The notification system was first described in PAT 28 in 2017, whereas the email templates editing section was added late 2019 (and is described in PAT 28, too − which can be confusing, and makes this PAT quite hard to follow).

Email templates

A not so long time ago, email templates were available and editable instance-wide, in the instance_settings file.

Now, email templates (e.g reset_password) have default values in default_email_templates.yml, but can be overriden both at the instance level and the small app level. The precedence order is:

  1. small app level (if exists)
  2. instance level (if exists)
  3. default email templates

Small app's email templates are located in the small app dedicated database, whereas instance templates live in the default database. More info in common/email_templates.py.

The make_email util adds some CSS to the emails, which are sent using sendgrid on our cloud, and with custom smtp providers on-premises.

Email templates are Jinja2 templates. Only some of the email templates are used by our native notifications. You can find the native notifications enum in laputa/models/email_templates/model.py. The list of variables available in Jinja2 templates can be found where send_notif_email is called.

For email templates not related to the notification system (e.g export_email), available variables will vary. For ease of editing, when you are making a new variable available, please also add it to the appropriate section of default_email_templates.yml.

Opt-out without needing to be logged in

User wants to be able to unregister from a notif from their mail client, without needing to be logged in. However we don't want them to be able to unregister other users! To do so, the variable notification_id is made available in email templates, and used like this:

<a href="{{ frontend_url }}/notification/opt-out/{{ notification_id }}">unregister</a>

It is a JWT containing the username and the notification identifier1. A client cannot craft such JWT by himself since he doesn't have the secret key.

See UserNotificationOptOut and user_notif_id for more details.

  1. You may ask "how can we have unique notif identifier?" since there is no such field in the notif config. This identifier is actually a hash of various variables identifying the notification (for example the username, the ID of the scheduled action, the small app ID and the string scheduled_action for a scheduled action). It is this hash which is stored in the user model notifications field. ↩