Customizable notifications

Goals/Scope

This list is in priority order:

1. Consolidated notifications
   • Customizable rules for consolidation
2. Add SMS as a notification channel
   • Configurable to use SMS or email
3. Administrator customization of notification messages
   • Notification messages support tokens
   • Customization of notification text for SMS and email
   • View history of sent notifications, maybe as an adhoc report (this is a future goal - what is the value of this?)

Background

• Different countries have different protocols and customs on how they notify individuals for different message types and what to say.
• Email notifications are supported for Requisition, Stock Management, Fulfillment, and User Password management. 
• Other related meeting notes: Meeting Notes: OpenLMIS Notification requirements, See "What are the needs" section of User management - Opting out
• Emergency requisitions and reset passwords are types of notifications that override user settings to opt-out. These notifications are always sent.
• The Who below is defined using User Personas.

Existing notifications in 3.5:

• Requisition notifications are sent when there is a requisition status change.
  • Users receive notification of a requisition status change 
  • Approver receives notification once a requisition has been submitted and authorized
  • User receives notification if their requisition has been rejected
  • User receives notification that their requisition has been converted to order
  • User receives notification that their requisition status has been updated to released without order (if configured to release without order)
• Fulfillment notifications are sent when there is an order status change.
  • User receives notification that an order has been created
  • User receives notification that an order is ordered
  • User receives notification that an order is fulfilled
  • User receives notification for FTP transfer status
• Stock management notifications are sent when there is low stock or a stockout event.
• CCE notifications are sent when there is an inventory status change that requires a user to take action.
• User profile notifications are sent any time the user or admin edits a user profile or password that requires the user to take action.
  • Adding or editing an existing email address 
  • Reset password scenarios

Requirement #1: Consolidated Notifications (Notifications Daily Digest)

• Enable consolidation of notification messages so the user doesn't receive multiple individual notifications by facility
• Daily digest of notifications (example: summary of # requisitions by status changes by facility or supervisory node or requisition group)

User Scenarios:

Roy or Sophie (the storeroom manager): a user who needs to receive notifications for their facility only - the current notifications are acceptable for this user (email notifications by a status update) this user probably doesn't need consolidated emails

• Problem: the user would prefer SMS or high-level notification for rejection type notifications
  • Value: user knows to act on notification immediately

Raquel or Apu (District Supervisor or has responsibilities for multiple facilities): a user who needs to receive notifications for facilities they supervise - this user receives many notifications and desires consolidation, this user only needs to receive an email notification when an action is required by them (Example: District supervisor who supervises 50 facilities, only wants to see ONE email notification instead of 50, or actually 50*3 for every status change)

• Problem: receive a lot of notifications and can't filter through them to determine what to act on, doesn't help them do their job, ignore notifications because there are so many, they don't receive notifications when it would be helpful for them to receive one - when a requisition hasn't been approved for # of days, hasn't been submitted for # of days
  • Value: The user is only notified when all requisitions are in a status where they have work to do, assists them with their job and prioritizing tasks
  • Value: Receiving summarized notifications for # of requisitions per facility (instead of an individual email notification for each requisition status change at each facility they supervise)

Requisitions Service consolidation for Requirement #1:

Option A: Consolidate requisition notifications by requisition status & supervised facility (supervisory node) 

1. All requisitions for my supervised facility are consolidated by status once daily (user sees # of requisitions in In_approval status for each of their supervised facilities)
   1. As an authorizer, I want to see the # of requisitions that have been submitted for my supervised facility, once a day. 
   2. As an authorizer, I only want to see a notification for the requisitions that are in submitted status at the time the notification is sent (Example: If a requisition has been authorized before the notification is scheduled to send, then I should not receive the notification that a requisition is ready to be authorized in my daily digest notification.)
   3. As an approver, I want to see the # of requisitions that are ready to approve for my supervised facility, once a day.
   4. As an approver, I only want to see a notification for the requisitions that are pending approval at the time the notification is sent. (Example: If a requisition has been approved before the notification is scheduled to send, then I should not receive the notification that a requisition is pending approval in my daily digest notification.)
2. Admin can configure Requisitions service to select which requisition statuses will be consolidated (this can be through API and does not require admin UI yet)
   1. As an administrator I want the flexibility to select one or many requisition statuses to send in one daily digest notification.
   2. As an administrator I want the ability to specify text for the daily digest notification. (We can create a standard template or default message.)
3. All emergency requisitions are not consolidated, but sent as the status is changed (this is current behavior)
4. All requisitions for my facility are consolidated by status once daily (user sees # of requisitions in each status for their facility instead of individual emails for each status change - lower priority)

Option B: Consolidate requisition notifications by facility

1. All requisitions are consolidated by facility once daily (user sees facility and list of requisitions that have been changed)
2. All requisitions for my supervised facility are consolidated by supervised facility (supervisory node) once daily (user sees supervised facility and list of all requisitions In_approval status)
3. Admin can configure Requisitions service to select a facility to consolidate notifications (either by supervised facility or by facility)

Notifications Service configuration for Requirement #1:

1. Admin can configure opt-out for Requisitions service notifications (does not opt-out of emergency requisitions notifications)
2. Admin can configure scheduled time to send consolidated notifications (Should the admin have options to select from? Daily, weekly, bi-weekly? Every Wednesday, etc. Admin can select or enter in what time notifications are sent.)

Sulu or Chappie (monitors health of supply chain or views status across multiple facilities): a user who logs in occasionally 

• Problem: What is the problem this user has with current notifications if any?
  • Value: What is the value we want to provide for this user?

Question: Does this type of user need to receive notifications?

Requirement #1a: Configurability

• Configuring which/how notifications can be consolidated  
• Configuring time that notifications will be sent (once daily)
• Enable selection of which channel to use to send a notification (SMS or email) 
  • For the first iteration, is it acceptable to have a default configuration for each notification class (listed in Open Question 7 below), and then allow for configurability in a future phase?
• Manual Resend notifications (future release - out of scope for 3.6)
• Timebound notifications (future release - out of scope for 3.6)
• Disable notifications for unused services (example: Malawi has stock management but does not use it and could potentially receive stock management notifications that are not used)
  • Is this really needed? Can this be customized by roles?
• OLMIS-5589 - Getting issue details... STATUS

User Scenarios:

Adam the administrator: an administrator or implementer that needs to configure notifications to send via SMS or email depending on the type or importance of the notification

• Problem: Current email notifications have no obvious level of importance to the user that receives them
  • Value: 

Raquel or Apu (District Supervisor or has responsibilities for multiple facilities): a user who needs to receive notifications for important actions that must be completed quickly and doesn't care about other types of notifications (Example: this user doesn't care about requisition status changes, they only care about a requisition pending approval or an emergency requisition)

• Problem: What is the problem this user has with current notifications, any? What is the problem that we want to solve for this user?
  • Value: What is the value we want to provide for this user?

Requirement #2: Support SMS channel as an option for notifications

• Configuring notifications to be sent via SMS.
• Admin can select to send notification via SMS and/or email
• Requiring a phone number for a user, and if a phone number doesn't exist then the user would receive an email instead. 

Requirement #3: Administrator customization of notification message templates

• Ability to configure and change the text used on email or SMS notifications template.
• Research using RapidPro or another existing service (Team Ona uses RapidPro)
• Support a more digest-like notification rather than a facility-specific notification (as shown in the example below
• Must be able to put values from the database (support tokens) when editing text 
• Admin has ability to view history of notifications (question #2 below)

Background:

• Notification message text was drafted in consultation with program managers
• The system is connected to a third party SMS gateway or Email system
• Status in eLMIS: Implemented.
• Status in OpenLMIS: Partially Implemented. Implementers can change by editing the strings in each service. Values can come from the database.

  Priority: High priority for Tanzania, Zanzibar, Zambia

Adam the administrator: the administrator or implementer that needs to customize the text to be used for different types of notifications

• Problem: The current notification template is generic and not meaningful to the user
  • Value: Enable customization of the notification text so that the admin can modify text for different notifications, and notification channels

Example:

Assumptions

User Stories

Diagrams

Existing notification workflow for requisitions is located here: Requisition States and Workflow

• Need workflows for Stock Management & Fulfillment, and User password notifications

Dependencies

Open Questions

Below is a list of questions to be addressed as a result of this requirements document:

Out of Scope

• Stock management notifications: configuration and any changes to notifications will be some future release
• CCE notifications: configuration and any changes to notifications will be some future release
• Push notifications: A supervisor dashboard/interface for late reporters to push notifications to different levels, with customizable notification text
• In-app notifications: an example provided by Angola for in-app notifications that alert users when products are going to expire