The Notification Management Service for DHIS2 Notifications is designed to facilitate the handling of notifications within DHIS2. Built using NodeJS, it acts as a mediator for openHIM, providing specific functionalities to manage notifications effectively.
To know the DHIS2 event structure, you can check DHIS 2 Maintenance (psi-mis.org), program stage: CWS Notifications.
Endpoint: POST {openHIM-env}/dhis2/notification
Description: Receives requests containing notification parameters and stores them within a DHIS2 server configured through a .env file. The service analyzes the provided information and, upon verification, saves the notifications as events within DHIS2. The payload must include the TrackEntityInstance for saving notifications as events. The service will return the proper HTTP status code and message to indicate the operation result.
Send a POST request to {openHIM-env}/dhis2/notification with the necessary parameters including the TrackEntityInstance for each notification.
{
//"project": string. LAC_HIV/ LAC_FP // not implemented
//"id": string. DHIS2 TEI or Mongo ID // not implemented
"tei": string. DHIS2 TEI,
"msg": string. Message text to send,
"channel": string. Accepted values: facebook whatsapp SMS,
"to": string. It could be a phoneNumber or facebook/whatsapp ID,
"templateId": string. The template ID. This ID is used for sending FBM/WA as well as for rquesting a reminder cancelation (see below),
"templateParams": string. Template parameter. Needs parse to string the value,
"eventDate": String. The datetime. You can check the format in the below example,
"sendNow": boolean. Indicates if the notification is an instant message. We don't want schedule the notification.
} |
Example Request for SMS:
{
"tei": "cMyjKYJtgSI",
"channel": "SMS",
"templateId": "template_3",
"msg": "hi",
"to": "+26658636836",
"templateParams": "",
"eventDate": "2024-02-23T13:18:30.800Z"
} |
Example Request for Facebook Messenger template:
{
"tei": "cMyjKYJtgSI",
"channel": "facebook",
"templateId": "template_3",
"templateParams": "{'quick_replies':[{'content_type':'text','image_url':'http://example.com/img/red.png','payload':'<POSTBACK_PAYLOAD>','title':'Red'},{'content_type':'text','image_url':'http://example.com/img/green.png','payload':'<POSTBACK_PAYLOAD><','title':'Green'}],'text':'Pick a color:'}",
"to": "1234jdj204",
"eventDate": "2023-11-23T13:18:30.800Z",
"sendNow": true
} |
Check Meta’s documentation at https://developers.facebook.com/docs/messenger-platform/send-messages/quick-replies for quick reply format and other formats that you may want to use to send your messages
We also can send a bundle of notifications:
{
"notifications": [
{ ... },
{ ... },
{ ... }
]
} |
Example Request:
{
"notifications": [
{
"tei": "cMyjKYJtgSI",
"msg": "hi",
"channel": "facebook",
"to": "+26658636836",
"templateId": "1",
"templateParams": "",
"eventDate": "2023-11-23T13:18:30.800Z"
},
{
"tei": "cMyjKYJtgSI",
"msg": "hi",
"channel": "facebook",
"to": "+26658636836",
"templateId": "3",
"templateParams": "",
"eventDate": "2023-11-23T13:18:30.800Z"
}
]
} |
Endpoint: PUT {openHIM-env}/dhis2/cancel-notification/
Description: Allows cancellation of notifications based on either Track Entity ID, template ID or Event ID. This will cancel the pending notifications to send. It doesn’t make sense to cancel a notification that has been sent, it could be confusing. The service will return the proper HTTP status code and message to indicate the operation result.
Canceling by Track Entitiy ID, we will cancel all the TEI events.
Canceling by event ID, we will cancel a single event.
Here we are going to see two examples of how to cancel a notification
Request: PUT {openHIM-env}/dhis2/cancel-notification
Attributes:
tei: The unique identifier associated with the Track Entity.
Body Request:
{
"tei": "019283SFD"
} |
Request: PUT {openHIM-env}/dhis2/cancel-notification
Attributes:
eventId: The unique identifier associated with the Event.
Body Request:
{
"eventId": "A019283FD"
} |
Request: PUT {openHIM-env}/dhis2/cancel-notification
Attributes:
tei: The unique identifier associated with the Track Entity.
templateId: It could be a string or array. Its value is the template identifier associated with the type of message to be canceled.
Body Request:
{
"tei": "019283SFD",
"templateId": ["template_3","appointment"],
} |
Body Request:
{
"tei": "019283SFD",
"templateId": "template_3",
} |
Upon successful cancellation, a confirmation response will be returned. If the operation encounters an issue or the notification cannot be canceled, appropriate error messages will be provided.
This cancel-notification endpoint allows for the cancellation of notifications either by the Track Entity ID or by the Event ID, providing flexibility in managing and removing notifications from the system. Adjust the specifications or examples as needed to align with your service implementation.
Endpoint: POST {openHIM-env}/dhis2/send-notifications
Description: Triggered by a cron job, this endpoint retrieves scheduled messages based on date ranges and the event status set as 'scheduled.' It prepares message content to be sent to a messaging service. After sending the messages, this service updates the event status and adds notes in case of message delivery failure or errors encountered within the messaging service.
We are using the cron service provided by OpenHIM.
The reason to do it by date ranges are both:
DHIS2 endpoints restrictions
We get the notifications pending to send before the current minute and after the previous 7 days. In this way, if for some reason we have notifications pending to send for any reason (the server was down, DHIS2 was not working in the previous hours…) we can send the previous notifications.
Trigger the cron job to send scheduled notifications by sending a POST request to {openHIM-env}/dhis2/send-notifications. Executing this, we will send the notifications until the current minute. We don’t need to add any information on the payload
The Notification Management Service simplifies the process of handling notifications within DHIS2. Its various endpoints enable the recording, scheduling, and querying of notifications efficiently.