Versions Compared

Version Old Version 20 New Version 21
Changes made by

Gaspar

Ricardo Gomez

Saved on

Key

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

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:

Table of Contents

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:

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

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

...

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:

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.

...

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
{
    //"projectnotifications": string. LAC_HIV/ LAC_FP // not implemented[
      {
          //"clientIdproject": string. DHIS2 TEI or Mongo ID // not implemented"",
          "clientId": "",
          "msg": "",
          "channel": "",
    "to": string. "",     "templateIdto": "",
          "templateId": "",
          "templateParams": "",
          "eventDatenotificationDate": "",
          "sendNow": false
        }
    ]
}

Parameter Name

Type

Description

clientIdproject

stringCould

Reference project to send notifications. This allows the app to store data in a different data persistence tool.

Supported values:

  • LAC-FP

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.

eventDatenotificationDate

string

Date on which the notification will be sent.

Format: YYYY-MM-DDTHH:MM:SS

sendNow

boolean

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

Request body SMS

Code Block
{
        "clientIdnotifications": "cMyjKYJtgSI",// add project, change to clientID [
      {
        "project": "LAC-FP",
        "clientId": "cMyjKYJtgSI",
        "channel": "SMS",
        "templateId": "template_3",
        "msg": "hi",
        "to": "+26658636836",
            "templateParams": "",
        "eventDatenotificationDate": "2024-02-23T13:18:30.800Z"
      }
    ]
}

Request body Facebook template

Code Block
{
    //project id
    "clientId": "cMyjKYJtgSI",
    "channelnotifications": [
    {
      "project": "facebookLAC-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}]
}
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.

...

Code Block
{
    "notifications": [
      {
 ... },       { ... } "project": "",
      { ... }  "clientId": "",
  ] }

Example Request:

Code Block
{   "notifications": [   "msg": "",
{         //project --> to be added "channel": "",
          "clientIdto":  "cMyjKYJtgSI",
//  replace by id          "msgtemplateId":  "hi",
          "channeltemplateParams": "facebook",
        "to": "+26658636836",          "templateIdeventDate":  "1",
         "templateParams": "",         "eventDate": "2023-11-23T13:18:30.800Z"
sendNow": false
   },     {},
        {  "clientId": "cMyjKYJtgSI",... },
         "msg": "hi",   { ... },
   "channel": "facebook",         "to": "+26658636836",...
         "templateId": "3",]
}

Example Request:

Code Block
{
  "notifications": [
    {
            "templateParamsproject":  "LAC-FP",
        "eventDate    "clientId": "2023-11-23T13:18:30.800Z"cMyjKYJtgSI",
    }
  ]
}

Example of response: (proposal)

Code Block
{
  "notifications": [    "msg": "hi",
     {   "channel": "facebook",
    200    "to": "+26658636836",
        "templateId": "1",
   sucsess - notification scheduled
        "clientId": string. DHIS2 TEI / mongoDB _id,     "templateParams": "",
        "eventDate": "2023-11-23T13:18:30.800Z"
        "msgsendNow": false
string. Message text to send},
    {
   "channel": string. Accepted values: facebook whatsapp SMS     "project": "LAC-FP",
        "toclientId": string. It could be a phoneNumber or facebook/whatsapp ID "cMyjKYJtgSI",
        "msg": "hi",
        "templateIdchannel": string. The template ID. This ID is used for sending FBM/WA as well as for rquesting a reminder cancelation (see below)"facebook",
        "to": "+26658636836",
        "templateId": "3",
        "templateParams": "",
        "eventDate": "2023-11-23T13:18:30.800Z",
        "templateParamssendNow": string.false
Template parameter. Needs parse to}
string the value,
]
}

Response

Code Block
{
  "notifications": [
   "eventDate": String. The datetime. You can check the format in the below example,{
          "notificationID": "",
          "sendNowproject": "",
 boolean         "statusclientId": scheduled "",
           }"msg": "",
      ]
}

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    "channel": "",
          "to": "",
          "templateId": "",
          "templateParams": "",
  "eventId        "eventDate": "",
          "clientIdstatus": "",
        },
        ...
  ]
}

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.

...

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
  "clientId": "",
  "templateId": "019283SFD",
// replace by client id
}

Request body to cancel by Event ID

Code Block
{ 
  //project --> to be added"notificationID": "",
  "eventIdclientId": "A019283FD"  // add project
}

Request body to cancel by TrackEntity ID & Multiple TemplateId

Code Block
{ 
  //project --> to be added
  "clientId": "019283SFD,
}

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:

  • LAC-FP

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

Code Block
{ 
  "project": "LAC-FP",
  "templateIdclientId": ["template_3","appointment"],019283SFD" // replace by client id
}

Request body to cancel by

...

Notification ID

...

Code Block
{ 
  //project --> to be added
  "clientId"project": "019283SFDLAC-FP",
  "templateIdnotificationId": "template_3A019283FD",
}

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": "",
       // add project
}

Request body to cancel by TrackEntity ID & Multiple TemplateId

Code Block
{ 
  "project": "LAC-FP",
  "clientId": "019283SFD",
  "templateId": ["template_3","appointment"],
}

Request body to cancel by TrackEntity ID & Single TemplateId

Code Block
{ 
  "project": "LAC-FP",
  "clientId": "019283SFD",
  "templateId": ["template_3"],
}

Response

Code Block
{
  "notifications": [
},   {
 {         "eventnotificationID": "",
          "statusproject": "",
          "templateIdclientId":  ""
    },
    {      "msg": "",
          "channel": "",
          "to": "",
          "eventtemplateId": "",
        "status": "",
        "templateId": ""
    },
    ...
]

...

Name

...

Type

...

Description

...

event

...

string

...

Id assigned to a notification.

...

status

...

string

...

Status of the current notification

...

templateId

...

string

...

  "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

Code Block
[
    {
          "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:

  • LAC-FP

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.

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:

  • LAC-FP

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.

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

...