Notifier by SFL

Notifier is an open-source notification sending & management microservice. We intend the project to be the primary way of sending all kinds of notifications or transactional messages to the user, be those e-mail, SMS, push notifications, or maybe even a WebSocket message (the last example is not implemented yet). Notifier’s source code is available on GitHub under the Apache 2.0 license.

We at SFL have many projects where notifications play an essential role. Initially, some ten years ago, everything notification-related was being repeatedly re-implemented in every project from scratch based on customized project requirements. However, once we began moving towards microservices about six years ago, things started to change. Components that were previously re-written per-project or, in better cases, were shared across projects as maven libraries started coalescing into distinct microservices. Notifier is such a microservice. The version published on GitHub is currently used in five projects in SFL. There are also about four projects that run a customized version of it, but we’re planning to migrate to the open-source version gradually.

We’ve open-sourced Notifier cause we see many reasons why someone may want to use it. These reasons include:

• Unified code/API for sending all types of notifications
• No need to research how each notification service works
• No need to implement the logic of saving the state of notifications per project
• Plugin mechanism for new notification services, so adding a new one ain’t a problem
• Unified templating
• Possibility to analyze/query data for sent notifications
• Single implementation for all notification-related cross-cutting concerns (logging, retry mechanism, etc.)
• If one operates in Armenia: magnificent support for Armenian SMS providers

We’ve also worked hard to make the use of it as streamlined and simple as possible. Of course, there’s still space for improvement, but we’ve reached the point where running it can be achieved within 15 minutes (yay docker-compose!), and integrating it with your project can be done within a couple of hours with our REST API or a provided maven client library.

As of now, Notifier supports the following notification engines:

Also, an interesting fact is that Notifier was first publicly presented during the first-ever EVN JUG’s meetup(Yerevan’s Java User Group). Here are the slides of the presentation:

Presentation at Yerevan’s Java user group’s meetup

Advanced features of the Notifier include templating and security. Internationalization work via FreeMarker. All types of notifications can be internationalized and templated. Internationalization can also be applied to templates selectively. Once a templated is translated into multiple languages, a proper locale has to be provided each time when sending a notification.

In case Notifier is used in a highly secure environment, an integration with a centralized OAuth2 service is available. We’re using this configuration with RedHat’s Keycloak. One may set permission requirements on sending notifications, and even fine-grained control by performing permission checking per notification template is supported. This may be especially handy if the system where Notifier is used uses microservices. In such a setup, distinct users, flows or even microservices can send only specific emails.

We recommend running Notifier in production in a two-component setup. The first component in an API that accepts requests to send notifications, saves them into a database, and queues them into a queue so the second component can pick them up from there. The second component picks the notification sending requests either via the queue or directly from the database and does the slow & routine work of sending them to the user.

Architecture and components of Notifier

In development, or if you simply don’t want to spin up a queue in production, it’s possible to run Notifier in a simplified configuration. In this setup, it will run as one component application that will both listen on an API and send notifications.

Getting up and running with Notifier is extremely easy. For development purposes, a docker-compose configuration is provided here. It’s not yet merged into the release branch but will be included in the next stable release.

Or you can use the publicly available docker images directly to start the api and worker modules directly. This may be useful if you’re running it in Kubernetes, as we are. The docker images are sflpro/notifier-api and sflpro/notifier-worker.

Once the service is started sending an email message is as simple as the following cURL command:

curl -X POST \  http://{notifier-host}/notification/email/create \ 
    -H 'Content-Type: application/json' \  
    -d '{ 
        "recipientEmail": "adam.smith@gmail.com",
        "senderEmail": "noreply@yourdomain.com", 
        "subject": "Hey!", 
        "body": "Hey! How are you?"
    }'

We, at SFL, will maintain the notifier in open source and push any update we have on it to the open-source repository. And while we’re at that any kind of feedback, be those bug reports or feature suggestions are highly valuable for us and will help us to steer the project in the direction of generating the most value for the users.

However, it will also greatly help the project if you, the community, also start sending PRs to the repo. Doing a PR is really easy:

• You create a fork on GitHub and from it do a PR to notifier’s develop branch. You can read more details on this in the CONTRIBUTING.md file on GitHub. (you do this)
• Travis will automatically build and run tests on your PR. If all tests pass, it will also run static code analysis with Sonar. Get your PR approved by Travis & Sonar. (you do this)
• At this point, we will review your pull request and merge it or otherwise provide feedback on it. (we do this)
• Right after the PR merge, the notifier client lib’s snapshot will be pushed to OSS Sonatype repository, and Docker images will be pushed to Docker Hub under the snapshot label. (CI does this)

Once the PR is merged, it will be published with the next release of the notifier. All client libraries will be pushed to Maven Central and Docker containers to Docker Hub.

I guess that was it. If you reached this point, thank you very much for bearing with me for this long, and hopefully, see you on GitHub!