added notification overview
This commit is contained in:
Shahed Nasser
@@ -3963,5 +3963,5 @@ You can also track analytics related to emails sent from the SendGrid dashboard.
|
||||
|
||||
## What’s Next 🚀
|
||||
|
||||
- Learn more about how [Notifications work in Medusa](../how-to/notification-api.md).
|
||||
- Learn more about how [Notifications work in Medusa](../advanced/backend/notification/overview.md).
|
||||
- Install the [Medusa admin](https://github.com/medusajs/admin#-setting-up-admin) for functionalities like Gift Cards creation, swaps, claims, order return requests, and more.
|
||||
92
docs/content/advanced/backend/notification/overview.md
Normal file
92
docs/content/advanced/backend/notification/overview.md
Normal file
@@ -0,0 +1,92 @@
|
||||
# Architecture Overview
|
||||
|
||||
This document gives an overview of the notification architecture and how it works.
|
||||
|
||||
## Introduction
|
||||
|
||||
Medusa provides a Notification API to mainly handle sending and resending notifications when an event occurs. For example, sending an email to the customer when they place an order.
|
||||
|
||||
The Notification architecture is made up of 2 main components: the Notification Provider and the Notification. Simply put, the Notification Provider handles the sending and resending of a Notification.
|
||||
|
||||
## Notification Provider
|
||||
|
||||
### Overview
|
||||
|
||||
A Notification Provider is a provider that handles sending and resending of notifications. You can either create and integrate your own provider or install a Notification Provider through a third-party plugin.
|
||||
|
||||
An example of a notification provider is SendGrid. When an order is placed, the SendGrid plugin sends an email to the customer.
|
||||
|
||||
### How it is Created
|
||||
|
||||
A Notification Provider is essentially a Medusa [Service](../services/create-service.md) with a unique identifier, and it extends the [`NotificationService`](../../../references/services/classes/NotificationService.md) provided by the `medusa-interfaces` package. It can be created as part of a [Plugin](../../../guides/plugins.md), or it can be created just as a service file in your Medusa server.
|
||||
|
||||
As a developer, you mainly work with the Notification Provider when integrating a third-party service that handles notifications in Medusa.
|
||||
|
||||
When you run your Medusa server, the Notification Provider is registered on your server if it isn’t already. This means that it will be inserted into the `notification_provider` table in your database.
|
||||
|
||||
### Entity Overview
|
||||
|
||||
The `NotificationProvider` entity only has 2 attributes: `id` and `is_installed`.
|
||||
|
||||
`id` is the value of the static property `identifier` defined inside the notification service class.
|
||||
|
||||
`is_installed` indicates whether the Notification Provider is installed or not. When you install a Notification Provider, the value of this attribute is `true`.
|
||||
|
||||
If you installed a Notification provider and then removed the service files or plugin that registered the Notification Provider, the Notification Provider remains in your database, but the value of the `is_installed` field changes to `false`.
|
||||
|
||||
## Notification
|
||||
|
||||
### Overview
|
||||
|
||||
A notification is a form of an alert sent to the customers or users to inform them of an action that has occurred. For example, if an order is placed, the notification, in this case, can be an email that confirms their order and lists the order details.
|
||||
|
||||
Notifications can take on other forms such as an SMS or a Slack message.
|
||||
|
||||
### How it is Created
|
||||
|
||||
Notifications are created in the `NotificationService` class in Medusa’s core after the Notification has been handled by the Notification Provider.
|
||||
|
||||
The data and additional details that the Notification Provider returns to the `NotificationService` is used to fill some of the attributes of the Notification in the database.
|
||||
|
||||
A Notification also represents a resent notification. So, when a notification is resent, a new one is created that references the original Notification as a parent. This Notification is also created by the `NotificationService` class.
|
||||
|
||||
### Entity Overview
|
||||
|
||||
The 2 most important properties in the `Notification` entity are the `to` and `data` properties.
|
||||
|
||||
The `to` property is a string that represents the receiver of the Notification. For example, if the Notification was sent to an email address, the `to` property holds the email address the Notification was sent to.
|
||||
|
||||
The `to` property can alternatively be a phone number or a chat username. It depends on the Notification Provider and how it sends the Notification.
|
||||
|
||||
The `data` property is an object that holds all the data necessary to send the Notification. For example, in the case of an order confirmation Notification, it can hold data related to the order.
|
||||
|
||||
The `data` property is useful when a notification is resent later. The same `data` can be used to resend the notification.
|
||||
|
||||
In the case of resent notifications, the resent notification has a `parent_id` set to the ID of the original Notification. The value of the `parent_id` property in the original Notification is `null`.
|
||||
|
||||
The `Notification` entity has some properties that determine the context of this Notification. This includes the `event_name` property which is the event that triggered the sending of this notification.
|
||||
|
||||
Additionally, the `resource_type` property is used to determine what resource this event is associated with. For example, if the `event_name` is `order.placed`, the `resource_type` is `order`.
|
||||
|
||||
You can also access the specific resource using the `resource_id` property, which is the ID of the resource. So, in case of the `order.placed` event, the `resource_id` is the ID of the order that was created.
|
||||
|
||||
The `Notification` entity also includes properties related to the receiver of the Notification. In case the receiver is a customer, the `customer_id` property is used to identify which customer.
|
||||
|
||||
## Automating Flows with Notifications
|
||||
|
||||
With Medusa you can create notifications as a reaction to a wide spectrum of events, allowing you to automate communication and processes.
|
||||
|
||||
An example of a flow that can be implemented using Medusa's Notification API is automated return flows:
|
||||
|
||||
- A customer requests a return by sending a `POST` request to the `/store/returns` endpoint.
|
||||
- The Notification Provider listens to the `order.return_requested` event and sends an email to the customer with a return invoice and return label generated by the Fulfillment Provider.
|
||||
- The customer returns the items triggering the `return.recieved` event.
|
||||
- The Notification Provider listens to the `return.received` event and sends an email to the customer with confirmation that their items have been received and that a refund has been issued.
|
||||
|
||||
## What’s Next 🚀
|
||||
|
||||
- Learn how to create your own Notification Provider.
|
||||
- [Check out the list of events in Medusa.](../subscribers/events-list.md)
|
||||
- [Check the `NotificationService` API reference for more details on how it works.](../../../references/services/classes/NotificationService.md)
|
||||
- [Check out the SendGrid Notification plugin.](../../../add-plugins/sendgrid.mdx)
|
||||
- Learn more about [Subscribers](../subscribers/create-subscriber.md) and [Services](../services/create-service.md) in Medusa.
|
||||
@@ -1862,4 +1862,4 @@ Object of the following format:
|
||||
## What’s Next 🚀
|
||||
|
||||
- Learn how you can [use services in subscribers](create-subscriber.md#using-services-in-subscribers).
|
||||
- Learn how to [create notifications](../../../how-to/notification-api.md) in Medusa.
|
||||
- Learn how to [create notifications](../notification/overview.md) in Medusa.
|
||||
|
||||
@@ -1,103 +0,0 @@
|
||||
---
|
||||
title: Notifications and automated flows
|
||||
---
|
||||
|
||||
# Notification API and how to structure email flows
|
||||
|
||||
### Introduction
|
||||
|
||||
Plugins offer a way to extend and integrate the core functionality of Medusa. For a walkthrough of the implementation details behind these, please see [Plugins in Medusa](https://docs.medusajs.com/guides/plugins).
|
||||
|
||||
Medusa makes it possible for plugins to implement the Notification API. The API allows for different types of implementations of notifications (emails, text messages, Slack messages, etc), that are sent as a reaction to events in Medusa. All Notifications are stored in the database with information about the receiver of the notification and what plugin was in charge of sending it. This allows merchants to resend notifications, but also gives an overview of what communication has been sent to customers.
|
||||
|
||||
### How it works
|
||||
|
||||
The Notification API works by subscribing to all events that are emitted to the Event Bus and channeling them through to notification plugins that listen to the events. In a plugin you can subscribe to a notification event by exporting a subscriber class that calls `notificationService.subscribe`:
|
||||
|
||||
```jsx
|
||||
// src/subscribers/my-notification.js
|
||||
|
||||
class MyNotification {
|
||||
constructor({ notificationService }) {
|
||||
// Subscribe to order.placed events
|
||||
notificationService.subscribe("order.placed", "my-service");
|
||||
}
|
||||
}
|
||||
|
||||
export default MyNotification;
|
||||
```
|
||||
|
||||
The above code tells the notification service to send `order.placed` events to the `my-service` notification service implemented in your plugin.
|
||||
|
||||
For a plugin to work with the Notification API you must implement 2 methods `sendNotification` and `resendNotification`;
|
||||
|
||||
```jsx
|
||||
// src/services/my-notification.js
|
||||
|
||||
class MyService extends NotificationService {
|
||||
static identifier = "my-service";
|
||||
|
||||
constructor({ orderService }, options) {
|
||||
super();
|
||||
|
||||
this.options_ = options;
|
||||
this.orderService_ = orderService;
|
||||
}
|
||||
|
||||
async sendNotification(eventName, eventData, attachmentGenerator) {
|
||||
let sendData;
|
||||
switch (eventName) {
|
||||
case "order.placed":
|
||||
sendData = await this.orderService_.retrieve(eventData.id);
|
||||
break;
|
||||
default:
|
||||
// If the return value is undefined no notification will be stored
|
||||
return;
|
||||
}
|
||||
|
||||
await CoolEmailSender.send({
|
||||
email: sendData.email,
|
||||
templateData: sendData,
|
||||
});
|
||||
|
||||
return { to: sendData.email, data: sendData };
|
||||
}
|
||||
|
||||
async resendNotification(notification, config, attachmentGenerator) {
|
||||
const recipient = config.to || notification.to;
|
||||
|
||||
await CoolEmailSender.send({
|
||||
email: recipient,
|
||||
templateData: notification.data,
|
||||
});
|
||||
|
||||
return { to: sendOptions.to, data: notification.data };
|
||||
}
|
||||
}
|
||||
|
||||
export default MyService;
|
||||
```
|
||||
|
||||
:::note
|
||||
|
||||
A notification service must have a static property called `identifier` this is used to determine which classes are called when subscribing to different events. In this case the service identifier is `my-service` so to subscribe to notifications you must use:
|
||||
`notificationService.subscribe([eventname], "my-service")`
|
||||
|
||||
:::
|
||||
|
||||
The above class is an example implementation of a NotificationService. It uses a fictional email service called `CoolEmailSender` to send emails to a customer whenever an order is placed. The `sendNotification` implementation gets the event name and fetches relevant data based on what event is being processed; in this case it retrieves an order, which is later used when requesting `CoolEmailSender` to dispatch an email. The address to send the email to is likewise fetched from the order.
|
||||
|
||||
The return type of `sendNotification` and `resendNotification` is an object with `to` and `data`. The `to` prop should identify the receiver of the notification, in this case an email, but it could also be a phone number, an ID, a channel name or something similar depending on the type of notification provider. The `data` prop contains the data as it was gathered when the notification was sent; the same data will be provided if the notification is resent at a later point.
|
||||
|
||||
When `resendNotification` is called the original Notification is provided along with a config object. The config object may contain a `to` property that can be used to overwrite the original `to`.
|
||||
|
||||
## Creating automated notification flows
|
||||
|
||||
When running an ecommerce store you typically want to send communication to your customers when different events occur, these include messages like order confirmations and shipping updates. With Medusa you can create transactional notifications as a reaction to a wide spectrum of events, allowing you to automate communication and processes. An example of a flow that can be implemented using Medusa's Notification API is automated return flows. Below is an outline of how an automated return flow might work.
|
||||
|
||||
- Customer requests a return with `POST /store/returns`
|
||||
- Notification Service listens for `order.return_requested` and sends email to the customer with a return invoice and return label generated by fulfillment provider
|
||||
- Customer returns items triggering `return.recieved`
|
||||
- Notification Service listens for `return.received` and sends email to the customer with confirmation that their items have been received and that a refund has been issued.
|
||||
|
||||
Check out `medusa-plugin-sendgrid` for an Notification API implementation that works with Sendgrid.
|
||||
@@ -182,8 +182,15 @@ module.exports = {
|
||||
]
|
||||
},
|
||||
{
|
||||
type: "doc",
|
||||
id: "how-to/notification-api",
|
||||
type: "category",
|
||||
label: "Notification",
|
||||
collapsed: true,
|
||||
items: [
|
||||
{
|
||||
type: "doc",
|
||||
id: "advanced/backend/notification/overview"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
type: "doc",
|
||||
|
||||
Reference in New Issue
Block a user