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.
Page content:
How does it works?
The following steps explains how does all the technology stack works together:
An external tool wants to perform an action on Notification Mediator Service.
The request goes to OpenHim that acts as an API Gateway.
OpenHim sends the request directly to the Notification Mediator Service to handle the operation.
Notification Mediator Service executes either:
A request information to a data persistence tool to retrieve data.
A delivery of information to the Communication Mediator Service.
After all the processes are executed, the Notifications Mediator service responds back to OpenHim.
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:
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
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
{
"notifications": [
{
"project": "",
"clientId": "",
"msg": "",
"channel": "",
"to": "",
"templateId": "",
"templateParams": "",
"notificationDate": "",
"sendNow": false
}
]
}
Parameter Name | Type | Description |
|---|---|---|
project | string | Reference project to send notifications. This allows the app to store data in a different data persistence tool. Supported values:
|
clientId | string | Could be:
|
msg | string | Message to be linked to the notification. |
channel | string | Way of communication where the scheduled message will be sent: Current supported values:
|
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. |
notificationDate | string | Date on which the notification will be sent. Format: |
sendNow | boolean | Parameter to specify if the notification should be sent on creation time. |
Request body SMS
{
"notifications": [
{
"project": "LAC-FP",
"clientId": "cMyjKYJtgSI",
"channel": "SMS",
"templateId": "template_3",
"msg": "hi",
"to": "+26658636836",
"templateParams": "",
"notificationDate": "2024-02-23T13:18:30.800Z"
}
]
}
Request body Facebook template
{
"notifications": [
{
"project": "LAC-FP",
"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}]
}
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:
{
"notifications": [
{
"project": "",
"clientId": "",
"msg": "",
"channel": "",
"to": "",
"templateId": "",
"templateParams": "",
"eventDate": "",
"sendNow": false
},
{ ... },
{ ... },
...
]
}
Example Request:
{
"notifications": [
{
"project": "LAC-FP",
"clientId": "cMyjKYJtgSI",
"msg": "hi",
"channel": "facebook",
"to": "+26658636836",
"templateId": "1",
"templateParams": "",
"eventDate": "2023-11-23T13:18:30.800Z"
"sendNow": false
},
{
"project": "LAC-FP",
"clientId": "cMyjKYJtgSI",
"msg": "hi",
"channel": "facebook",
"to": "+26658636836",
"templateId": "3",
"templateParams": "",
"eventDate": "2023-11-23T13:18:30.800Z",
"sendNow": false
}
]
}
Response
{
"notifications": [
{
"notificationID": "",
"project": "",
"clientId": "",
"msg": "",
"channel": "",
"to": "",
"templateId": "",
"templateParams": "",
"eventDate": "",
"status": "",
},
...
]
}
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.
The status update will be applied only if the notification has not being sent.
Request Body
{
"project": "",
"templateId": "",
"notificationID": "",
"clientId": "",
}
Parameter Name | Type | Description |
|---|---|---|
project | string | Reference project to send notifications. This allows the app to store data in a different data persistence tool. Supported values:
|
templateId | string | Identifier used by the specified channel to use a pre-defined template. |
notificationID | string | Id assigned to a notification. |
clientId | string | Id assigned to a client. |
Request body to cancel by TrackEntity ID
{
"project": "LAC-FP",
"clientId": "019283SFD" // replace by client id
}
Request body to cancel by Notification ID
{
"project": "LAC-FP",
"notificationId": "A019283FD" // add project
}
Request body to cancel by TrackEntity ID & Multiple TemplateId
{
"project": "LAC-FP",
"clientId": "019283SFD",
"templateId": ["template_3","appointment"],
}
Request body to cancel by TrackEntity ID & Single TemplateId
{
"project": "LAC-FP",
"clientId": "019283SFD",
"templateId": ["template_3"],
}
Response
{
"notifications": [
{
"notificationID": "",
"project": "",
"clientId": "",
"msg": "",
"channel": "",
"to": "",
"templateId": "",
"templateParams": "",
"eventDate": "",
"status": "",
},
...
]
}
Notification status:
Cancelled
Sent
Scheduled
Error
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.
Get Notifications
POST /notification/status/{project}/{clientId}
Get Notifications endpoint 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
[
{
"notificationID": "",
"project": "",
"clientId": "",
"msg": "",
"channel": "",
"to": "",
"templateId": "",
"templateParams": "",
"notificationDate": "",
"status": "",
},
{
"notificationID": "",
"project": "",
"clientId": "",
"msg": "",
"channel": "",
"to": "",
"templateId": "",
"templateParams": "",
"notificationDate": "",
"status": "",
},
{
"notificationID": "",
"project": "",
"clientId": "",
"msg": "",
"channel": "",
"to": "",
"templateId": "",
"templateParams": "",
"notificationDate": "",
"status": "",
},
...
]
Parameter Name | Type | Description |
|---|---|---|
project | string | Reference project to send notifications. This allows the app to store data in a different data persistence tool. Supported values:
|
clientId | string | Could be:
|
msg | string | Message to be linked to the notification. |
channel | string | Way of communication where the scheduled message will be sent: Current supported values:
|
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. |
notificationDate | string | Date on which the notification will be sent. |
status | string | Current status of the notification |
Get Notification by ID
POST /notification/status/{project}/{clientId}/{notificationID}
Get Notifications endpoint retrieves a single notification 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. |
{notificationID} | string | ID assigned to a notification. |
Response
Parameter Name | Type | Description |
|---|---|---|
project | string | Reference project to send notifications. This allows the app to store data in a different data persistence tool. Supported values:
|
clientId | string | Could be:
|
msg | string | Message to be linked to the notification. |
channel | string | Way of communication where the scheduled message will be sent: Current supported values:
|
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. |
notificationDate | string | Date on which the notification will be sent. |
status | string | Current status of the notification |
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.
This endpoint is meant to be triggered by a cron job provided by OpenHIM. However, Send Notifications endpoint is exposed so the users can manually trigger the sending of notifications
There are two main reasons to do it by date ranges:
DHIS2 endpoints restrictions
We get the notifications pending to send 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.
