Mediator: Notifications (DHIS2 or Mongo backend)

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:

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:

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

{
    //"project": string. LAC_HIV/ LAC_FP // not implemented
    //"clientId": string. DHIS2 TEI or Mongo ID // not implemented
    "tei": ""
    "msg": "",
    "channel": "",
    "to": string. "",
    "templateId": "",
    "templateParams": "",
    "eventDate": "",
    "sendNow": false
}

Request body SMS

{
    "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

{
    //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
}

We also can send a bundle of notifications:

{
    "notifications": [
      { ... },
      { ... },
      { ... }
    ]
}

Example Request:

{
  "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"
    }
  ]
}

Example of response: (proposal)

{
  "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.

Request Body

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

Request body to cancel by TrackEntity ID

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

Request body to cancel by Event ID

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

Request body to cancel by TrackEntity ID & Multiple TemplateId

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

Request body to cancel by TrackEntity ID & Single TemplateId

{ 
  //project --> to be added
  "tei": "019283SFD", // replace by id
  "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

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

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

Path Parameters

Response

[
    {
        "event": "",
        "status": "",
        "templateId": ""
    },
    {
        "event": "",
        "status": "",
        "templateId": ""
    },
    {
        "event": "",
        "status": "",
        "templateId": ""
    },
    ...
]

Message sending Endpoint → move to a dedicated page

POST /dhis2/send-notifications
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.

Scheduled 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