Extension Point: Notification Events · Extension Point Framework

Basics

Parameter	Value
Extension Point Key	`NOTIFICATION_EVENT`
Extension Point Name	Notification Events
Extension Interface	NotificationEvent
Supports Multiple Extensions?	Yes
Selector Type	None
Available Since	1.4.0

Use Cases

Extensions implementing this Extension Point are notified when Self-Managed Commerce needs to send notifications to customers or business users. Usually these are sent via email, but other methods of communication could be implemented.

The XPFNotificationDeliveryContext contains the information needed to send the notification, including the notification type, recipients, and placeholder values.

`CM_USER_PASSWORD_RESET`

This notification type is sent to a Commerce Manager user when they request a password reset.

The following placeholder values are available for the CM_USER_PASSWORD_RESET notification type:

Placeholder Key	Type	Description
`locale`	Locale	The locale of the Commerce Manager user.
`firstName`	String	The first name of the Commerce Manager user.
`lastName`	String	The last name of the Commerce Manager user.
`username`	String	The username of the Commerce Manager user.
`newPassword`	String	The new password of the Commerce Manager user.

`CM_USER_PASSWORD_CHANGED`

This notification type is sent to a Commerce Manager user when their password is changed.

The following placeholder values are available for the CM_USER_PASSWORD_CHANGED notification type:

Placeholder Key	Type	Description
`locale`	Locale	The locale of the Commerce Manager user.
`firstName`	String	The first name of the Commerce Manager user.
`lastName`	String	The last name of the Commerce Manager user.
`username`	String	The username of the Commerce Manager user.
`newPassword`	String	The new password of the Commerce Manager user.

`CM_USER_CREATED`

This notification type is sent to a Commerce Manager user when they are created.

The following placeholder values are available for the CM_USER_CREATED notification type:

Placeholder Key	Type	Description
`locale`	Locale	The locale of the Commerce Manager user.
`firstName`	String	The first name of the Commerce Manager user.
`lastName`	String	The last name of the Commerce Manager user.
`username`	String	The username of the Commerce Manager user.
`newPassword`	String	The new password of the Commerce Manager user.

`CUSTOMER_PASSWORD_CHANGED`

This notification type is sent to a customer when they change their password.

The following placeholder values are available for the CUSTOMER_PASSWORD_CHANGED notification type:

Placeholder Key	Type	Description
`locale`	Locale	The preferred locale for the customer.
`store`	XPFStore	The store that the customer is associated with.
`customer`	XPFCustomer	The details of the customer requesting the new password.

`CUSTOMER_PASSWORD_FORGOTTEN`

This notification type is sent to a customer when they forget their password.

The following placeholder values are available for the CUSTOMER_PASSWORD_FORGOTTEN notification type:

Placeholder Key	Type	Description
`locale`	Locale	The preferred locale for the customer.
`store`	XPFStore	The store that the customer is associated with.
`customer`	XPFCustomer	The details of the customer requesting the new password.
`newPassword`	String	The new password for the customer.

`CUSTOMER_REGISTRATION`

This notification type is sent to a customer when they register for an account.

The following placeholder values are available for the CUSTOMER_REGISTRATION notification type:

Placeholder Key	Type	Description
`locale`	Locale	The preferred locale for the customer.
`store`	XPFStore	The store that the customer is associated with.
`customer`	XPFCustomer	The details of the customer registering for an account.

`CUSTOMER_ANONYMOUS_REGISTRATION`

This notification type is sent to a customer when their account is converted from a single-session shopper to a registered shopper.

The following placeholder values are available for the CUSTOMER_ANONYMOUS_REGISTRATION notification type:

Placeholder Key	Type	Description
`locale`	Locale	The preferred locale for the customer.
`store`	XPFStore	The store that the customer is associated with.
`customer`	XPFCustomer	The details of the customer converting to an single-session user.
`password`	String	The new password for the customer.

`IMPORT_JOB`

This notification type is sent to a customer when an import job has completed.

The following placeholder values are available for the IMPORT_JOB notification type:

Placeholder Key	Type	Description
`locale`	Locale	The locale of the Commerce Manager user who triggered the import.
`userName`	String	The username of the Commerce Manager user who triggered the import.
`firstName`	String	The first name of the Commerce Manager user who triggered the import.
`lastName`	String	The last name of the Commerce Manager user who triggered the import.
`importJobName`	String	The name of the import job that was triggered.
`startTime`	Instant	The start time of the import job.
`endTime`	Instant	The end time of the import job.
`totalRows`	int	The total number of rows processed by the import job.
`succeededRows`	int	The number of rows that were successfully imported.
`failedRows`	int	The number of rows that failed to import.
`leftRows`	int	The number of rows that were not imported.

`GIFT_CERTIFICATE`

This notification type is sent to a customer when they receive a gift certificate.

The following placeholder values are available for the GIFT_CERTIFICATE notification type:

Placeholder Key	Type	Description
`locale`	Locale	The locale of the order that contains the gift certificate.
`store`	XPFStore	The store that the order was placed in.
`senderEmail`	String	The email address of the customer who sent the gift certificate.
`senderName`	String	The name of the customer who sent the gift certificate.
`recipientEmail`	String	The email address of the customer who received the gift certificate.
`recipientName`	String	The name of the customer who received the gift certificate.
`purchaseAmount`	BigDecimal	The amount of the gift certificate.
`purchaseCurrencyCode`	String	The currency code of the gift certificate.
`giftCertCode`	String	The code of the gift certificate.
`message`	String	The message entered by the sender for the recipient.

`ORDER_CONFIRMATION`

This notification type is sent to a customer when they place an order.

The following placeholder values are available for the ORDER_CONFIRMATION notification type:

Placeholder Key	Type	Description
`locale`	Locale	The locale of the order.
`store`	XPFStore	The store that the order was placed in.
`order`	XPFOrder	The details of the order that was placed.

`ORDER_CANCELLATION`

This notification type is sent to a customer when their order is cancelled.

The following placeholder values are available for the ORDER_CANCELLATION notification type:

Placeholder Key	Type	Description
`locale`	Locale	The locale of the order.
`store`	XPFStore	The store that the order was placed in.
`order`	XPFOrder	The details of the order that was cancelled.

`ORDER_SHIPMENT_SHIPPED`

This notification type is sent to a customer when their shipment is shipped.

The following placeholder values are available for the ORDER_SHIPMENT_SHIPPED notification type:

Placeholder Key	Type	Description
`locale`	Locale	The locale of the order.
`store`	XPFStore	The store that the order was placed in.
`order`	XPFOrder	The details of the order associated to the shipment.
`shipment`	XPFShipment	The details of the shipment that was shipped.

`ORDER_SHIPMENT_RELEASE_FAILED`

This notification type is sent to a customer if a shipment cannot be released.

The following placeholder values are available for the ORDER_SHIPMENT_RELEASE_FAILED notification type:

Placeholder Key	Type	Description
`locale`	Locale	The locale of the order.
`store`	XPFStore	The store that the order was placed in.
`order`	XPFOrder	The details of the order associated to the shipment.
`shipment`	XPFShipment	The details of the shipment that could not be released.
`errorMessage`	String	The error message that was returned by the shipment release process.

`ORDER_RETURN_EXCHANGE`

This notification type is sent to a customer when their order is returned or exchanged.

The following placeholder values are available for the ORDER_RETURN_EXCHANGE notification type:

Placeholder Key	Type	Description
`locale`	Locale	The locale of the order.
`store`	XPFStore	The store that the order was placed in.
`order`	XPFOrder	The details of the order that was returned.
`orderReturn`	XPFOrderReturn	The details of the order return.

`ORDER_ON_HOLD`

This notification is sent to business users when there are orders on hold.

The following placeholder values are available for the ORDER_ON_HOLD notification type:

Placeholder Key	Type	Description
`locale`	Locale	The store default locale.
`store`	XPFStore	The store that has held orders.
`heldOrderCount`	Long	The number of orders that are on hold for the store.

Methods

`getDeliveryPolicy`

The getDeliveryPolicy method is invoked during Integration Server startup. It allows the extension to define how retries should be handled if the extension throws an exception. The extension needs to return the following values in the XPFDeliveryPolicy response object:

consumerQueueName: An identifier for the consumer message queue that will be used to track events and allow them to be processed asynchronously. This value should be unique for all extensions assigned to this extension point.
maximumRedeliveries: The maximum number of redelivery attempts before the message is sent to the dead letter queue.
redeliveryDelay: The delay between redelivery attempts, in milliseconds.

`send`

The send method is invoked when a notification needs to be sent.

Extension Sample

@SuppressWarnings("checkstyle:magicnumber")
@Extension
@XPFAssignment(extensionPoint = XPFExtensionPointEnum.NOTIFICATION_EVENT, priority = 100)
public class SendGridEmailSender extends XPFExtensionPointImpl implements OrderReleaseEvent {

    @Override
    public XPFDeliveryPolicy getDeliveryPolicy() {
        XPFDeliveryPolicy xpfDeliveryPolicy = new XPFDeliveryPolicy();
        xpfDeliveryPolicy.setConsumerQueueName("sendgrid");
        xpfDeliveryPolicy.setMaximumRedeliveries(10);
        xpfDeliveryPolicy.setRedeliveryDelay(10000); // 10 seconds
        return xpfDeliveryPolicy;
    }

    @Override
    public void send(final XPFNotificationDeliveryContext context) {
        for (XPFNotificationRecipient recipient : context.getRecipients()) {
            if (StringUtils.isEmpty(recipient.getEmailAddress())) {
                LOG.debug("Skipping delivery of {} email because recipient email address is missing", context.getType());
                continue;
            }
            // Render an HTML document from a template, using `context.getType()` to determine the type and the `context.getPlaceholderValues()` to populate the template contents.
            // Send an email containing the HTML document to `recipient.getEmailAddress()`, using `recipient.getDisplayName()` as the recipient name.
       }
    }
}