README.md

notification-service

Deployment

1. Download the docker-compose.yml.

2. Download the platform templates and configure your platforms or create your own platform config.

3. Change the mounted directory inside the docker-compose.yml matching your path.

4. Deploy the service using docker compose / stack: docker-compose up or docker stack -c docker-compose.yml.

Getting Started

1. Make sure you have NodeJS and npm installed.

2. Install the dependencies

   npm install
   

3. Start the app

   npm start
   

Testing

Simply run npm test and all your tests in the test/ directory will be run.

This requires a running redis and email service locally. For email some alternatives exist.

Redis setup

Redis setup on OSX

Simply install redis via Brew

  brew install redis
  brew services start redis

Email setup

1. Setting process.env.MAIL_SERVICE = 'ethereal' before test execution will create temporarily an email account on ethereal. The credentials will be printed in the console and used to view delivered emails on that service. Therefore login with user and pass as password and list messages received. If doing so, there is no need to setup a mail service locally.
2. A local mail service may be defined on localhost:1025 which is used in the github test action too.

Architecture

To construct our notifications service, we structured our project in several different components from top to bottom. Aside from the high-level message service, a templating service, an escalation service, a device service and low level sending services are needed. For a more detailed insight, how these services collaborate, let us go through a small exemplary workflow:

At the beginning, an API user sends a message to our notification service. Internally the message service gets activated first. This service retrieves external user resources in case that the receivers attribute of the sent message is an URL. It expects an API endpoint that fulfils the JSON API specification for pagination. Finally, the message object gets enriched with the provided receivers. In the end, we store this message in our message DB.

The message service calls our escalation logic in the next step. The escalation logic plans the escalation on the given notification preferences of the user resources. Depending on the actual notification preferences, push and/or mail messages will be sent. Before sending the final messages, we first need to construct them with the templating service. This service creates different templates for the different channels (push and mail) and the different languages (defined in the languagePayloads attribute of the message). It then uses the appropriate templates to construct the final messages by inserting the payload for each single user.

At the end, the escalation logic sends the final messages according to some specific escalation settings (defined in the config.json) to the low level sending services. It sends the final push messages to the push service and the final mail messages to the mail service. Both services are then responsible for the eventual delivery of the messages.

We also have the device service: this service is only responsible for managing the device tokens. The device tokens are necessary to deliver the push notifications to the different devices.

External services can mark specific messages as seen to disable the escalation logic for a specific user. If the push message was delivered and this message was marked as seen via the respective API call, the mail message will not be sent.

Config

To use multiple Mail Configs (for example for load balancing) just use an array of options in the mail config.

{
  "mail": {
    "options": [
      {
        "host": "mail",
        "port": 1025,
        "secure": false,
        "auth": {
          "user": "",
          "pass": ""
        }
      },
      ...
    ],
    "defaults": {
      "from": "Sample Service <sample@sample.org>",
      "envelope": {
        "from": "Bounce <bounce@sample.org>"
      },
      "delay": 0
    }
  }

Docs

A Swagger Docs is available at /docs

License

Copyright (c) 2018

Licensed under the MIT license.