Versions Compared

Version Old Version 18 New Version 19
Changes made by

Rodolfo Melia

Ricardo Gomez

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Introduction

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.

tocThe Notifications Mediator service allows external tools to setup and schedule notifications for clients. This notifications act as reminders, so the user are aware of future activities. This, together with the Communication Mediator Service, allows the sending of the notifications through different communication channels.

Page content:

Table of Contents

How does it works?

The following steps explains how does all the technology stack works together:

  1. An external tool wants to perform an action on Notification Mediator Service.

  2. The request goes to OpenHim that acts as an API Gateway.

  3. OpenHim sends the request directly to the Notification Mediator Service to handle the operation.

  4. Notification Mediator Service executes either:

    1. A request information to a data persistence tool to retrieve data.

    2. A delivery of information to the Communication Mediator Service.

  5. After all the processes are executed, the Notifications Mediator service responds back to OpenHim.

  6. OpenHim delivers a response to the external tool, letting the external tool to know if something went wrong or if everything was successful.

The following diagram shows how the technology stack is connected:

...

Info

To know the DHIS2 event structure, you can check DHIS 2 Maintenance (psi-mis.org), program stage: CWS Notifications.

...

Authentication

...

Missing information here

...

Schedule

...

Notification

Endpoint: POST {openHIM-env} /dhis2notification/notification
Description: Receives requests containing notification parameters and stores them within a DHIS2 server configured through a .env file. The service schedule

Schedule Notification endpoint allows the creation and scheduling a notification. The service then receives requests containing the required parameters, 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.

...

Schedule Notification

Send a POST request to {openHIM-env}/dhis2/notification with the necessary parameters including the TrackEntityInstance for each notification.

notification in a data persistence tool.

...

Request Body

Code Block
{
    //"project": string. LAC_HIV/ LAC_FP // not implemented
    //"idclientId": string. DHIS2 TEI or Mongo ID // not implemented
    "tei": string. DHIS2 TEI, // to be discontinue (replaced by id) ""
    "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.
}

...

false
}

Parameter Name

Type

Description

tei

string

ID associated to a DHIS2 TrackedEntityInstance.

msg

string

Message to be linked to the notification.

channel

string

Way of communication where the scheduled message will be sent:

Current supported values:

  • facebook

  • whatsapp

  • SMS

to

string

Identifier used by the specified channel to send the message.

templateID

string

Identifier used by the specified channel to use a pre-defined template.

templateParams

string

Parameters to be used in the template specified.

eventDate

string

Date on which the notification will be sent.

sendNow

boolean

Parameter to specify if the notification should be sent on creation time.

Request body SMS

Code Block
{
    "tei": "cMyjKYJtgSI",// add project, change to clientID
    "channel": "SMS",
    "templateId": "template_3",
    "msg": "hi",
    "to": "+26658636836",
    "templateParams": "",
    "eventDate": "2024-02-23T13:18:30.800Z"
}

...

Request

...

body Facebook

...

template

...

Code Block
{
    //project id
    "tei": "cMyjKYJtgSI", // change for client id
    "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
}
Info

Check

...

out official Meta’s quick replies for facebook documentation to know more about the structure to use in templateParams parameter when the channel is.

We also can send a bundle of notifications:

...

Code Block
{
  "notifications": [
    {
        //project --> to be added
        "tei": "cMyjKYJtgSI", // replace by id
        "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"
    }
  ]
}

2. Cancel Notifications Endpoint

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.Example of response: (proposal)

Code Block
{
  "notifications": [
    {
        200
        sucsess - notification scheduled
        "tei": string. DHIS2 TEI, // to be discontinue (replaced by id)
        "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
        "status": scheduled 
    }
  ]
}

...

Cancel Notification

POST /notification/cancel

Cancel Notification endpoint allows to update the status of a notification to ‘cancelled’. 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

Input by TrackEntity ID

Request: PUT {openHIM-env}/dhis2/cancel-notification

Attributes:

  • tei: The unique identifier associated with the Track Entity.

...

Info

The status update will be applied only if the notification has not being sent.

...

Request Body

Code Block
{ 
  //project --> to be added
  "tei": "", 
  "templateId": "",
  "eventId": ""
  "clientId": "" 
}

Parameter Name

Type

Description

tei

string

ID associated to a DHIS2 TrackedEntityInstance.

templateId

string

Identifier used by the specified channel to use a pre-defined template.

eventId

string

Id assigned to a notification.

clientId

string

Id assigned to a client.

Request body to cancel by TrackEntity ID

Code Block
{ 
  //project --> to be added
  "teiclientId": "019283SFD" // replace by client id
}

...

Request body to cancel by Event ID

...

Request: PUT {openHIM-env}/dhis2/cancel-notification

Attributes:

  • eventId: The unique identifier associated with the Event.

...

Code Block
{ 
  //project --> to be added
  "eventId": "A019283FD"  // add project
}

...

Request body to cancel by TrackEntity ID &

...

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:

Multiple TemplateId

Code Block
{ 
  //project --> to be added
  "tei": "019283SFD", // replace by id
  "templateId": ["template_3","appointment"],
}

...

Request body to cancel by TrackEntity ID & Single TemplateId

Code Block
{ 
  //project --> to be added
  "tei": "019283SFD", // replace by id
  "templateId": "template_3",
}

...

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.

...

Notification Status

POST/notification/status/{project}/{clientId}

Notification Status endpoints retrieves all the notifications associated to a client in a specified project.

Path Parameters

Name

Type

Description

{project}

string

The name of the project where the client is going to be searched on.

{clientId}

string

Id assigned to a client.

Response

Code Block
[
    {
        "event": "",
        "status": "",
        "templateId": ""
    },
    {
        "event": "",
        "status": "",
        "templateId": ""
    },
    {
        "event": "",
        "status": "",
        "templateId": ""
    },
    .

...

3. Message sending Endpoint

...

..
]

Name

Type

Description

event

string

Id assigned to a notification.

status

string

Status of the current notification

templateId

string

ID of notification template used to scheduled a message to a client.

...

Message sending Endpoint → move to a dedicated page

POST /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.

...

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

Conclusion

The Notification Management Service simplifies the process of handling notifications within DHIS2. Its various endpoints enable the recording, scheduling, and querying of notifications efficiently.