Configure Notification for an Organization

This document outlines the process of setting up and triggering notifications for providers and patients within the Azodha platform.

Setting up Custom notification on the Platform

Integrating a notification service, such as FCM, is essential for utilizing the Notification API. This can be configured within your organization settings. If you prefer to send notifications directly to your patients or providers, please proceed to Step 5: Notification API

Step 1: Create a Webhook Configuration for the Organization

A webhook event is a platform feature that allows integration between systems by sending HTTP requests to a specified URL when certain events occur. You will need to configure webhook settings for each organization.

Database Models:

WebhookEvent Model This model represents the events that will trigger a webhook.

model WebhookEvent {
  name                 String                 @unique
  attributes           Json?
}

WebhookConfiguration Model This model holds the configuration for the webhook, including the URL, headers, and event associations. model WebhookEvent {

model WebhookConfiguration {
  name                 String
  organization         Organization   
  attributes           Json?
  secret               String?
  url                  String?
  headers              Json?
  webhookEvent         WebhookEvent     @relation(name: "WebhookEventToWebhook", fields: [webhookEventId], references: [id])
  active               Boolean          @default(true)
  isDeleted            Boolean          @default(false)
  sendOrganizationCode Boolean?         @default(false)
}

Example Configuration:

{
  "name": "Appointment Notifications",
  "organizationID": 5,
  "attributes": {},
  "secret": "ZvXvxtz8D8RCbnq7fbGa",
  "url": "https://7plagricjlngs47ux2qoorbvk40auvqm.lambda-url.us-west-2.on.aws/",
  "headers": {
    "api_key": "3e9583ee-5ecb-40bc-be50-2d01ef30faed",
    "organization_code": "dev-care2u"
  },
  "webhookEventID": 9,
  "active": true,
  "isDeleted": false,
  "sendOrganizationCode": true
}

Please refer to the guide below on more details on webhook events

Webhook Guide

Step 2: Trigger a Webhook Event

Whenever an event occurs (e.g., an appointment is booked), you need to trigger the corresponding webhook. Example:

await this._externalEventService.processEventToQueue(
  eventData,
  orgUrlCode,
  eventName,
  {
    api_key: organization.apiKey,
    orgUrlCode: orgUrlCode,
  }
);

This code sends the event data to a queue, such as RabbitMQ, through the ExternalEventService

Step 3: Platform Event Worker

A worker process listens to the queue. Once it receives a message, it does the following:

1. Checks the corresponding webhook event.

2. Retrieves the URL and headers from the webhook configuration.

3. Builds the HTTP request body from the message.

4. Sends the HTTP request using the gathered details (URL, headers, body).

Step 4: Client Custom Logic (CCL) for Notifications

The URL defined in the webhook configuration usually points to a custom logic server. This server processes the message and performs the following tasks:

1. Identifying the Recipients: Checks whether the message is for a patient or service provider.

2. User Role Identification: Determines the users and their roles for notification purposes.

3. Message Selection: Based on the event and event subtype, selects the appropriate message content.

4. Notification Type: Chooses between instant or scheduled notifications.

Once the server processes the message, it makes an API call to the Notification API.

Step 5: Notification API

The Notification API is responsible for dispatching messages based on the recipient's role (service provider or patient).

1. User Lookup:

   • Retrieves the personId of the user using the external ID.

   • Determines the communication channels available for the user.

2. Channel-Based Notification Handling:

   • Email Notification: Uses the user's email address.

   • Text (SMS) Notification: Uses the user's mobile number.

   • Push Notification: Uses the notification token from the communication data table.

Email Notifications

For sending email notifications, the nodemailer package is used.

const transporter = nodemailer.createTransport({
  host: settings.smtpHost,
  port: 587,
  auth: {
    user: settings.smtpUser,
    pass: settings.smtpPass,
  },
});

await engine.parseAndRender(emailContent, body.data)
  .then(result => emailContent = result)
  .catch(error => logger.error(error));

await transporter.sendMail({
  to: body.emailData.to,
  cc: body.emailData.cc,
  bcc: body.emailData.bcc,
  from: body.emailData.from ?? settings.senderEmailId,
  subject: body.emailData.subject,
  html: emailContent,
  attachments: body.emailData.attachments,
});

Text Notifications (SMS)

For SMS notifications, Twilio is used.

const accountSid = settings.twilioAccountSid;
const authToken = settings.twilioAuthToken;
const client = new Twilio(accountSid, authToken);

const messageInstance = await client.messages.create({
  body: body.textData.body,
  from: this._formatNumber(body.textData.from),
  to: this._formatNumber(body.textData.to),
});

Push Notifications

For push notifications, Firebase Cloud Messaging (FCM) is used.

const headers = {
  "Content-Type": "application/json",
  Authorization: `Bearer ${accessToken}`,
};

const message = {
  token: notificationToken,
  notification: {
    title: data.title,
    body: data.body,
  },
  data: {
    data: JSON.stringify(extraData),
  },
  webpush: {
    headers: {
      TTL: "30", // Expire in 30 seconds
    },
  },
};

const response = await this._axiosHttpClientUtil.post(
  `https://fcm.googleapis.com/v1/projects/${serviceAccount.project_id}/messages:send`,
  { message },
  headers
);