Creating notification services

What are notification services

Notification services as defined by this project are external plugin services that user coded tasks can use, these services are also be user coded. Their goal is to handle notifications in similar ways to gotify the default notification service used by this project. in future iterations, new notification services can be used as the default one.

Notification services also need to be registered the same way for tasks, and attached to the tasks that intend to use them, otherwise tasks will not find them and this may create crashes.

The notification services have to follow an interface defined in NotificationInterface (for future reference);

import { notificationServices } from "@generated/prisma_base"
import { JobDTO, JobLogDTO } from "@typesDef/models/job"
import { IScheduleJobLog } from "schedule-manager"

export interface Notifications {
  init?(
    job: JobDTO,
    jobLogDTO: JobLogDTO | IScheduleJobLog,
    serviceDbObject: notificationServices,
  ): Notifications
  name?: string
  description?: string
  serviceDbId?: number

  sendMessage(message: string, title?: string): Promise<any>
}

Notification services must implement at least :

• a static init function that will return a new instance of the service
• a generic sendMessage method that will execute the notification “broadcast”

Main functions and properties

init()

This is the main function for generating instances of the service, the reasoning behind using a static function instead of a constructor is simply to offer more flexibility to the service developers on which instance to send to the tasks when given the input objects. This is also still in development and can be changed in the future.

• Params:
  • job: the job object, the same passed to the run method.
  • jobLogDTO: the task instance object (aka log object), the same passed to the run method.
  • serviceDbObject: the service object coming from the database after registering teh service.
• Returns: an instance of Notifications or a class that implements it.

sendMessage()

This basic function for sending notifications, it is advised to use this message internally also in your service implementation.

• Params:
  • message : the message body in string format
  • title (optional): the title of the message in string format
• Returns: Promise(any) : the result of the notification broadcast

name

Optional, the name of the notification service. this will be displayed in future cases by the system if found.

description

Optional, the description of the notification service. this will be future by the system if found.

serviceDbId

Optional, the database row id for this service on registration. if this is not present the system will treat the service as not registered.

Tutorial : Creating a notification service

Here’s an example of a simple notification service that logs messages to the console and stores them in the database:

import { notificationServices } from "@generated/prisma_base"
import { JobDTO, JobLogDTO } from "@typesDef/models/job"
import { Notifications } from "@typesDef/notifications"
import { IScheduleJobLog } from "schedule-manager"
import { addNotifications } from "@repositories/notification"

class TestNotificationService implements Notifications {
  serviceDbId?: number
  jobLogId?: string
  constructor(job: JobDTO, jobLogDTO: JobLogDTO | IScheduleJobLog) {}
  async sendMessage(message: string, title?: string): Promise<any> {
    console.log(`${message} from test notification service title: ${title}`)
    await addNotifications({
      message: title,
      service_id: this.serviceDbId,
      job_log_id: this.jobLogId,
      data: message,
    })
    return Promise.resolve(
      `${message} from test notification service title: ${title}`,
    )
  }
  static init(
    job: JobDTO,
    jobLogDTO: JobLogDTO | IScheduleJobLog,
    serviceDbObject: notificationServices,
  ): TestNotificationService {
    const instance = new TestNotificationService(job, jobLogDTO)
    instance.serviceDbId = serviceDbObject.id
    instance.jobLogId = jobLogDTO.id
    return instance
  }
}

export default TestNotificationService

Here we are implement the basic method sendMessage to send the notification. We also choose to save the notification ot the database using addNotifications.

Adding the notification service and attaching to a task

The notification service needs to be registered by sending an API request to the backend server or by using the UI. the service creation body must have :

• name (UNIQUE): the service name,
• description (optional): the service description,
• entryPoint: the service entry point,
• image (optional): the service image,
• jobs (optional): an array of job ids that the service will be attached to on creation. cna be attached later on.

The API request is sent via the /notifications/addNotificationService endpoint and the content type is multipart/formdata as we are sending an image data. here is how the UI dialog will look like :

Attaching the notification service to a task

Attaching notification services to a tas can be done via the API or the UI, the input is simple :

• serviceId: the id of the service to attach (can be an array of or a single number),
• jobId: the id of the job to attach the service to (can be an array of or a single number).

The request cna be done via the /notifications/attachServiceToJob endpoint with a POST request and a appliation/json content type. (more on the API reference) You can also attach services via the creattion/update dialog mentioned above, or the job attaching dialog :

Example usage in a Task

To use this notification service within a task, you would first need to register it and attach it to your task (via the API / UI). Attaching the notification service requires setting a name for it which we will then using to access teh notification service instance. Once attached, you can access the new service via the notificationServices property of the JobConsumer base task..

Here’s an example of a task that uses the TestNotificationService to send a notification:

import { JobConsumer } from "@jobConsumer/jobConsumer";
import { JobDTO, JobLogDTO, JobOptions } from "@typesDef/models/job";


class MyTask extends JobConsumer {
  async run(job: JobDTO, jobLog: JobLogDTO): Promise<any> {
    this.logEvent("Task is starting...");

    if (this.notificationServices[<<serviceName>>]) {
      this.notificationServices[<<serviceName>>]?.sendMessage("test message");
    }
     return await super.complete(jobLog, `Finished`);
  }

}

export default MyTask