Target release	3.6
Epic	OLMIS-1094 - Getting issue details... STATUS
Document status	DRAFT
Document owner	Sam Im (Deactivated)
Technical Lead	Nikodem Graczewski (Unlicensed)

Goals/Scope

This list is in priority order:

Consolidated notifications
- Customizable rules for consolidation
Add SMS as a notification channel
- Configurable to use SMS or email
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)

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.)
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.)
All emergency requisitions are not consolidated, but sent as the status is changed (this is current behavior)
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)

Example for authorizer

Header: Requisition Status update

Dear divo1:

This email is informing you that 20 Regular requisitions for EPI at Depósito Distritial Cuamba have been authorized.

Please login to see the requisitions.

Hyperlink to OpenLMIS requisitions here

Example for approver that needs to take action

Header: Action Required

Dear psupervisor:

This email is informing you that 20 Regular requisitions for EPI at Depósito Distrital Cuamba are ready for review.

Please login to see the requisitions.

Hyperlink to OpenLMIS requisitions approve here

Option B: Consolidate requisition notifications by facility

All requisitions are consolidated by facility once daily (user sees facility and list of requisitions that have been changed)
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)
Admin can configure Requisitions service to select a facility to consolidate notifications (either by supervised facility or by facility)

Example for approver that needs to take action

Header: Action Required

Dear divo1:

This email is informing you that Regular requisitions at 15 facilities are ready for review.

Please login to see the requisitions.

Hyperlink to OpenLMIS Requisitions approve here

Notifications Service configuration for Requirement #1:

Admin can configure opt-out for Requisitions service notifications (does not opt-out of emergency requisitions notifications)
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

#

Title

User Story

Label

Importance

Notes

1

2

Diagrams

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

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

Dependencies

Description	Link

Open Questions

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

#	Question	Outcome	Status
1	Is OLMIS-3796 - Getting issue details... STATUS still required?	SMS needs to be included in the feature set. Multiple countries mentioned that cost is not a concern as phone companies provide messages for free.	Answered
2	If SMS is no longer required - are there any requirements in Notifications - Push Reminders that we will need to support? Push notifications from an admin to all users happen through JIRA. Is this enough?	Only user stories 1 and 2 are required for the initial version: Add SMS as a channel for notification Notification for Rejected requisitions by SMS or email based on configuration	Answered - #3 - Log of SMS and email notifications sent (may be included in scope if this can be done efficiently in 3.6)
3	Phone numbers are already captured in User Profile page - but there is only minimal validation on format. Is this required? It would be required if SMS is included in this feature.	Phone number format validation needs to be updated.	Answered
4	Need to research solutions for customizing messages in other languages	Messages need to be configurable but not localized	Answered
5	Who is the user that logs in occasionally? Do they need to receive notifications to remind them to log in and check something?	Understanding this user will help us ensure we support notification scenarios for this user.	Wesley Brown to confirm
6	Are there more types of notifications that could be categorized as high level?	Helps us understand which notifications would override a user's opt-out preferences.	Wesley Brown to confirm (maybe with help from Nikodem Graczewski (Unlicensed) to understand current state - emergency requisitions, reset password, are there others?)
7	Should we classify types of notifications so that we all agree on terms to use? Informative notifications: Requisition status updates (would notifications about upcoming system updates, planned system outages be included in this classification?) Action-based (action-oriented) notifications: Notifications that require the user to log into OpenLMIS to take action, some action-based notifications would override the user's notification preferences such as emergency requisitions or reset password email notifications. Time-bound notifications (or reminder notifications?): Notifications that remind a user something needs to be done, or hasn't been done yet - should be done Are there default settings for each notification class that would be acceptable? Informative notifications: defaulted to email (and scheduled email only once a day - for requisition status updates) Action-based: defaulted to SMS or email (with Action required or links in the email to complete an action) Time-bound: defaulted to scheduled email (once a day?) What classifications should be used for notifications of system updates or planned system outages? This is a message that is configured by an administrator and then set to all users. (Malawi example, or is slack good enough?).	Gain agreement on terminology so we understand what notifications are supported and must be supported. Helps explain the value and use for each type.	Sam Im (Deactivated): This is a design discussion. This does not mean that notifications must be designed with a classification but is used to help us understand the value of notifications for each user. FYI Wesley Brown As of Dec 18th, and discussed in PC Meeting on Dec 18th: Two types of notifications will be supported in 3.6: Urgent and non-urgent Urgent: Emergency requisitions, password reset Need to add support for Reject notifications as an urgent notification that overrides opt-out settings. (per question #2 requirements) Non-urgent: all other notifications Other classifications may be discussed for a future release
8	What are other generalized needs for requisitions and stock management notifications that we may need to consider in the future design - but allow for in our current design?	Customizing stock management notification messages Configuring stock management notifications via SMS or email Push notifications Resending notifications (what are the use cases we would need to support?) Disabling notifications
9	Are we supporting fulfillment notifications in 3.6 scope?		Wesley Brown to confirm (maybe with help from Nikodem Graczewski (Unlicensed) to understand current state of fulfillment type notifications)
10	Design questions: Are we required to allow users to opt-out of SMS notifications? Should we allow users to override SMS notification settings? Should users (in their own user profile) be allowed to choose SMS instead of email? What types of limitations in characters should be required for SMS? Should this message be different or shorter than the email notification? What happens if SMS is configured for notifications, but there is a problem sending SMS or receiving SMS?	Rejected requisitions should override opt-out settings	Nikodem Graczewski (Unlicensed) here are some questions that have come up about SMS so far.
11	Known issue: If a user is not assigned to a supervisory node, then they will not receive notifications. This is not related to opting-out but is a problem caused by misconfiguration and can be confusing during configuration. How should this issue be handled?		FYI Nikodem Graczewski (Unlicensed)

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

Browser not supported