Notification Backbone System Description Overview The notification backbone service is intended to provide an enterprise-scale publish/subscribe model for applications and services to communicate electronically with people. To quote the proposal: Cross-system solution for personalised notifications and emergency communications. Enables notifications to be created-by and distributed-across multiple University systems. This will allow users to received notifications from key services in a unified way, and optionally in future allow the people being communicated with to choose the medium in which they are contacted.

Service Description The service is split into 4 major components (the following links are to source control). 1. 2. 3. 4.

An OAuth Server The Notification MicroService The Notification UI The Notification Portlet

NOTE: For more general details of what OAuth2 is and how we are using it, refer to the OAuth2 server page.

Data Model Notify Schema

NOTE: The above schema does not include the Quartz scheduler tables (see quartz-jdbcstore-er-diagram.pdf), nor the Liquibase tables which are two simple tables and self explanatory.

OAuth SCHEMA

NOTE: The above schema does not include the Liquibase tables, which are two simple tables and self explanatory.

Reporting There is currently no reporting.

Technology All components are written in Java, and have an underlying Oracle Database back end. For the components we use the Spring framework, with the following main dependencies/libraries: Spring Boot 1.2.x (at time of writing 1.2.2.RELEASE) Spring-boot-starter-web Spring-boot-starter-data-rest Spring-boot-starter-data-pa JSON-path Swagger (at time of writing 1.0.2) Oracle JDBC Driver Spring-security-oauth2 (at time of writing 2.0.5.RELEASE) Spring-cloud-starter-security (at time of writing 1.0.0.RELEASE) org.jsoup HTML parser (at time of writing version 1.8.3) Liquibase

Software Tools IDE All components are written in Java, any modern Java IDE will work (e.g. Eclipse, Netbeans, IntelliJ, Spring Source Tool Suite).

Bamboo deployment The software has 4 build plans: notification-ms (The Notification Micro Service) OAuthServer (The OAuth Server) Notification Backbone UI (The notification Backbone UI) NotificationPortlet (Overlay) In addition, each of the components has a related deployment plan to release the software onto environments: Notification-ms Deployment OAuthServer Deployment Notification Backbone UI Deployment NOTE: The Notification Portlet currently has no deployment plan as it was created along with the other MyEd plans. For details on how to use Bamboo refer to the Continuous Integration tasks and scenarios page. For details on MyEd bamboo deployments refer to the Bamboo MyEd deployment guide.

Interfaces and services Learn publisher The learn publisher runs from the Notification UI and pulls the following data from Learn by querying the database, in the process converting them into user notifications: System level announcements Course level announcements Assessments Tasks See /src/main/java/uk/ac/ed/notify/service/LearnService for details (entry method is pullLearnNotifications()). The publisher is scheduled to run via a Quartz scheduler.

Office 365 publisher The Office 365 publisher runs from the Notification UI and pulls from a specific mailbox in Office 365, and converts valid emails to notifications, supporting insert/update/delete operations. It makes use of the Office 365 REST API to retrieve mail. See /src/main/java/uk/ac/ed/notify/service/Office365ApiService for details (entry method is processUnreadEmail(token)). The publisher will only accept emails which contain a valid publisherKey, and contain a JSON object in the following format embedded in a script tag in the email:

"example notification body", "example title", "http://www.ed.ac.uk" "rgood", "2013-05-15T08:30", "2013-05-20T08:30", "insert"

Additionally the mailbox will be set to only allow messages from certain senders. Each environment is set to use a different mailbox in Office 365, e.g. one for DEV, one for TEST, and one for LIVE notifications. The publisher is scheduled to run via a Quartz scheduler.

Notification Microservice The notification microservice is a web API providing authorised publishers access to create/update/delete notifications, and also for authorised subscribers to retrieve notifications by user or publisher. It interacts with the NOTIFY schema, and uses OAuth2 for authorisation. NOTE: The notification micro service API is documented using Swagger. See the micro service links below to view the micro service API documentation.

Notification Portlet The notification portlet pulls information using the Notification MicroService on demand, authorising by passing client credentials.

Access, Authentication and Authorisation Authentication Authentication is handled via EASE

Authorisation Microservice Authorisation to the micro service is handled by OAuth. The following clients are set up: myed - client_credentials grant type access notification-ui - client_credentials grant type access notification-api-ui - implicit grant type access

Notification UI Authorisation to the notification UI is handled by User/Role access, and administrable via the UI. Currently there are two roles set up: EMERGENCY - Allow creation, and maintenance of emergency notifications. USERADMIN - Allow administration of users. Roles are stored in NOTIFICATION_UI_ROLES table. Users are stored in NOTIFICATION_UI_USERS table. User roles are stored in NOTIFICATION_UI_USER_ROLES table.

Access BETA Notification Portlet: https://www-beta.myed.ed.ac.uk/uPortal/f/s874/p/notification.n937/max/render.uP

DEV Notification UI: https://dev.notifyadm.is.ed.ac.uk/ DEV Notification Microservice: https://dev.notify.ws-apps.is.ed.ac.uk DEV Notification Portlet: https://www-dev.myed.ed.ac.uk/uPortal/p/notification.ctf2/max/render.uP

Delivery

The backbone consists of a micro service API, which makes use of an OAuth server. There is a portlet in MyEd for users to view their notifications, and a separate notification UI for administrators to create/view/delete emergency notifications.

Support details Documentation http://www.liquibase.org/documentation/index.html - Liquibase documentation http://www.quartz-scheduler.org/documentation - Quartz Scheduler documentation http://docs.spring.io/spring-boot/docs/current-SNAPSHOT/reference/htmlsingle/ - Spring Boot reference guide http://jsoup.org - JSoup HTML parser

Standard tasks Database patching Liquibase is used as the database patching tool for the OAuth and Notifications database. All of the patches can be applied simply by deploying the application to the environment, as when the application starts up it checks whether there are any SQL scripts to apply. Liquibase is essentially intended to be used when you are making structural changes to the database which would also require code changes, as it is deployed with the application. That doesn't mean you can't use it for data changes also if it's convenient to do so!

For example to create a new sql script for the NOTIFY schema Put the new SQL script in src/main/resources/db/changelog/sql Add an entry in src/main/resources/db/changelog/db.changelog-master.xml (for example the following below) Check the code in, then apply it to the environment you wish to patch using Bamboo. You can see the status and list of previous patches applied to the environment by looking at the table DATABASECHANGELOG.

Altering Quartz scheduler timings The Notification UI handles executing tasks on a schedule using Quartz. If you need to alter the schedule at all, the settings are applied using Bamboo. In /u01/app/bamboo/home/isapps/connections/notification-ui--application.properties (e.g. notification-ui-dev-application.properties), look for #Quartz scheduler properties. Each of the jobs is set to run on a frequency, and that frequency is set in milliseconds. Simply adjust the job frequency you wish to change, then deploy to the environment you wish to change. For example to set the Learn pull job to run every 60 minutes, set: learnPullJob.frequency=3600000

Troubleshooting Guide Error checking Each of the applications will log in tomcat. Refer to the following locations: /u01/app/notifygp/oauthsec/apache-tomcat/logs/oauth2.log (The OAuth server logs) /u01/app/notifygp/notify/apache-tomcat/logs/notification-ms.log (The Notification Microservice log) /u01/app/notifygp/notifyadm/apache-tomcat/logs/notification-ui.log (The Notification UI log) In addition to above, the NOTIFY schema contains the table NOTIFICATION_ERRORS, which is used to store any serious errors.

Audit checking The notification backbone contains a table USER_NOTIFICATION_AUDIT which contains entries related to user notifications. You can use this to identify anything which happened at the user notification level.