The 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.
...
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. |
...
Cronjob
Missing information here
Schedule Notification
POST /notification/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 notification in a data persistence tool.
...
Request Body
| Code Block |
|---|
{
//"project": string. LAC_HIV/ LAC_FP // not implemented
//"clientId": string. DHIS2 TEI or Mongo ID // not implemented
"clientId": ""
"msg": "",
"channel": "",
"to": string. "",
"templateId": "",
"templateParams": "",
"eventDate": "",
"sendNow": false
} |
...
Parameter Name
...
Type
...
Description
...
clientId
...
string
...
Could be:
ID associated to a DHIS2 TrackedEntityInstance.
_id associated to a mongoDB client document.
...
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 |
|---|
{
"clientId": "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
"clientId": "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
} |
| 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": [
{ ... },
{ ... },
{ ... }
]
} |
Example Request:
| Code Block |
|---|
{
"notifications": [
{
//project --> to be added
"clientId": "cMyjKYJtgSI", // replace by id
"msg": "hi",
"channel": "facebook",
"to": "+26658636836",
"templateId": "1",
"templateParams": "",
"eventDate": "2023-11-23T13:18:30.800Z"
},
{
"clientId": "cMyjKYJtgSI",
"msg": "hi",
"channel": "facebook",
"to": "+26658636836",
"templateId": "3",
"templateParams": "",
"eventDate": "2023-11-23T13:18:30.800Z"
}
]
} |
Example of response: (proposal)
| Code Block |
|---|
{
"notifications": [
{
200
sucsess - notification scheduled
"clientId": string. DHIS2 TEI / mongoDB _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 clientId events. Canceling by event ID, we will cancel a single event.
| Info |
|---|
The status update will be applied only if the notification has not being sent. |
...
Request Body
| Code Block |
|---|
{
//project --> to be added
"templateId": "",
"eventId": ""
"clientId": ""
} |
Parameter Name | Type | Description |
|---|---|---|
clientId | string | ID associated to a DHIS2 TrackedEntityInstance or _id associated to a MongoDB client document. |
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
"clientId": "019283SFD" // replace by client id
} |
Request body to cancel by Event ID
| Code Block |
|---|
{
//project --> to be added
"eventId": "A019283FD" // add project
} |
Request body to cancel by TrackEntity ID & Multiple TemplateId
| Code Block |
|---|
{
//project --> to be added
"clientId": "019283SFD",
"templateId": ["template_3","appointment"],
} |
Request body to cancel by TrackEntity ID & Single TemplateId
| Code Block |
|---|
{
//project --> to be added
"clientId": "019283SFD",
"templateId": "template_3",
} |
Response
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.
Notification Status
...
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": ""
},
...
] |
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. |
Send Notifications → move to a dedicated page
POST /dhis2/send-notifications
Send Notification endpoint retrieves all scheduled messages up to the time the endpoint is called and where the notification status is set as 'scheduled'. This endpoint prepares message content to be sent to Communication Mediator Service. After sending the messages, this service updates the notification status. Additional notes are included in the notification in case of message delivery failure or errors encountered within the messaging service.
...
Notification Mediator Service use a cron scheduler to send all the notifications that have already reached the scheduled date and which status is set to 'scheduled'. This CronJob runs every 2 minutes.
The cronjob uses notification endpoint named send notifications.
There are two main reasons to do it by date ranges:
DHIS2 endpoints restrictions
We get the notifications Notifications pending to send are retrieved before the current minute and after the previous 7 days. 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.
...
