Event Notifications Module

The Event Notifications module lets you configure notifications for events that occur in the Medusa backend. All from the admin dashboard, without the need to write any subscriber code. Notifications are sent via the base MedusaJS Notification module - you can use any channel that you have configured in your application (see MedusaJS docs for more information on the Notification module).

#Notification Configurations

A notification configuration is a record that defines the behavior of a notification for a specific event. Create a new notification configuration by using the "Create Notification" button on the Notification Manager page in the admin dashboard.

• Name & Description (name, description) - Does not influence the behavior, purely organizational.
• Event (event) - The event for which the notification will be sent. This can be any event that is emitted in the Medusa backend, either core or custom events. Please note that for custom events, additional configuration is necessary (see below).
• Channel (channel) - The channel through which the notification will be sent. This can be any channel that you have configured in your MedusaJS Notification module.
• Template (template) - The template that will be used for the notification. This relates to the template field used in the MedusaJS Notification module.
• Recipient Options (recipient_options), Target Options (target_options), Custom Recipients (custom_recipients), Custom Targets (custom_targets) - see below.

#Recipients & Targets

Recipients are the MedusaJS actors that will receive the notification, while targets are the resolved destinations where the notification will be sent.

For example, a recipient can be a customer and the target can be the customer's email address or phone number.

Recipients are eventually resolved to targets when processing the notification, and the notification is sent to the resolved targets via the selected channel.

#Destination Options

Destination options are the Recipient and Target options mentioned in the notification configuration. Those are pre-defined options that are resolved by the module based on the event data. For most core events, the following are present:

• Recipient Options
  • Event Target - The main actor related to the event. For example, for the order.placed event, the event target is the customer who placed the order.
  • Administrators - All administrators in the system.
• Target Options - those are not defined by default for core events, except for the feed channel, where Admin UI Feed is available as a target option, which sends the notification to the in-app feed of all administrators.

#Custom Destinations

When configuring the notification, you can also specify custom recipients and targets. This is useful for sending notifications to actors that are not directly related to the event or for sending notifications to fixed destinations (e.g. a specific email address or phone number).

For the custom recipients, you will need to input the actor type and its ID.

For the custom targets, you will need to input the target value (e.g. email address or phone number).

#Extensions

The module comes with a set of pre-defined components for processing the notifications. Certain extensions may be necessary for compatibility with your notification providers or for adding the recipient and target options for custom events.

#Event Definitions

A Notification Event is a record that defines the behavior of a notification for a specific event.

Notification Event definitions use a middleware-like stack to processing the notifications. The notification event middleware can be used for multiple puproses such as adding recipient and target options, manipulation of the template data and other custom logic.

Please note that for most use cases, the default event definitions are sufficient and no additional configuration is necessary.

class EventNotificationContext {
    definition: EventNotificationDefinition;
    event: EventNotificationMiddlewareEvent;
    record: InferTypeOf<typeof EventNotification>;
    container?: Record<string, any>;

    addRecipients: (optionKey: string, recipients: NotificationRecipient[]) => void;
    addTargets: (optionKey: string, targets: string[]) => void;

    registerRecipientOptions: (options: EventRecipientOptionDefinition[]) => void;
    registerTargetOptions: (options: EventTargetOptionDefinition[]) => void;

    getRecipientsByOption: () => Record<string, NotificationRecipient[]>;
    getTargetsByOption: () => Record<string, string[]>;

    mergeTemplateData: (data: Record<string, unknown>) => void;
    getTemplateData: () => Record<string, unknown>;
}

#Actor Resolvers

Since MedusaJS Notification Module Providers do not automatically resolve actors to the destination values, the Event Notifications module provides a way to define these resolvers for the notification channels used. To define an actor resolver, use the defineNotificationActorResolver, as shown below:

const resolveCustomerEmailTargets: ActorResolverHandler = async (args) => {
    const query = getQueryFromContext(args)

    if (!query) {
        return []
    }

    const customerIds = Array.from(
        new Set(
            args.recipients
                .map((recipient) => recipient?.actor_id)
                .filter((value): value is string => !!value)
        )
    )

    if (!customerIds.length) {
        return []
    }

    const { data } = await query.graph({
        entity: "customer",
        fields: ["id", "email"],
        filters: { id: customerIds },
    })

    return Array.from(
        new Set(
            (data || [])
                .map((customer: Record<string, CustomerModelType>) => customer.email)
                .filter(
                    (value: unknown): value is string =>
                        typeof value === "string" && value.length > 0
                )
        )
    )
}

defineNotificationActorResolver({
    actor_type: "email",
    channel: "email",
    handler: resolveCustomerEmailTargets,
    metadata: {} // optional metadata for the resolver
}),