Migration Notes 5.2 to 5.3

These migration notes assumes that you are going from a Heat Clinic 5.2 demo to the 5.3 demo. There might be additional migration steps necessary for your particular implementation of Broadleaf. If so, please let us know through our Gitter, our Google Group, or by submitting a pull request to this documentation repo at https://github.com/BroadleafCommerce/docs.

Overview of new features in the 5.3.0-GA release are detailed within [[5.3.0-GA Release Notes | 5.3.0 GA]].

This document also assumes that you are on the latest 5.2 GA patch version of Broadleaf (at time of writing, 5.2.2-GA). If you have not upgraded your site to be on the latest 5.2 patch version, please do so before continuing and see the optional migration docs for each 5.2 patch version.

Module Compatibility with 5.3

If you are using any other Broadleaf modules, then those module versions will need to be updated to be compatible with broadleaf framework 5.3. Here is a compatibility chart listing all of the module versions that are compatible with broadleaf 5.3.

Schema Changes

There are a number of schema changes involved in the upgrade from 5.2.x to 5.3.0-GA. Be sure to check the migration notes for each sub-module. For core, the schema changes necessary can be found below. As always, we recommend using liquibase and Hibernate update to generate a changelog to be sure things are accurate for your environment.

<changeSet id="0" author="developer">
    <addColumn tableName="BLC_OFFER_AUDIT">
        <column name="ACCOUNT_ID" type="bigint"/>
    </addColumn>
</changeSet>

<changeSet id="1" author="developer">
    <createIndex tableName="BLC_OFFER_AUDIT" indexName="OFFERAUDIT_ACCOUNT_INDEX">
        <column name="ACCOUNT_ID"/>
        <column name="OFFER_ID"/>
    </createIndex>
</changeSet>

<changeSet id="2" author="developer">
    <dropIndex tableName="BLC_OFFER_AUDIT" indexName="OFFERAUDIT_CUSTOMER_INDEX"/>
</changeSet>

<changeSet id="3" author="developer">
    <createIndex tableName="BLC_OFFER_AUDIT" indexName="OFFERAUDIT_CUSTOMER_INDEX">
        <column name="CUSTOMER_ID"/>
        <column name="OFFER_ID"/>
    </createIndex>
</changeSet>

<changeSet id="4" author="developer">
    <addColumn tableName="BLC_OFFER">
        <column name="MAX_USES_STRATEGY" type="varchar(255)"/>
    </addColumn>
</changeSet>

<changeSet id="5" author="developer">
    <addColumn tableName="BLC_OFFER">
        <column name="USE_LIST_FOR_DISCOUNTS" type="boolean"/>
    </addColumn>
</changeSet>

<changeSet id="6" author="developer">
    <sql>
        CREATE TABLE BLC_OFFER_PRICE_DATA (
            OFFER_PRICE_DATA_ID bigint PRIMARY KEY NOT NULL,
            END_DATE timestamp,
            START_DATE timestamp,
            AMOUNT numeric NOT NULL,
            ARCHIVED char(255),
            CREATED_BY bigint,
            DATE_CREATED timestamp,
            DATE_UPDATED timestamp,
            UPDATED_BY bigint,
            DISCOUNT_TYPE varchar(255),
            ADMIN_ADDITION_STATUS varchar(255),
            CATALOG_DISC bigint,
            SNDBX_CATALOG_FLAG bigint,
            SNDBX_ORIG_ITEM_ID bigint,
            SNDBX_ORIG_RECORD_ID bigint,
            SNDBX_ID bigint,
            SNDBX_ARCHIVED_FLAG char(255),
            SNDBX_DELETED_FLAG char(255),
            SNDBX_TMPLT_RECORD_ID bigint,
            SNDBX_TIER bigint,
            IDENTIFIER_TYPE varchar(255),
            IDENTIFIER_VALUE varchar(255),
            QUANTITY integer NOT NULL,
            OFFER_ID bigint NOT NULL,
            CONSTRAINT FKE0B2C929D5F3FAF4 FOREIGN KEY (OFFER_ID) REFERENCES BLC_OFFER (OFFER_ID)
        );
        CREATE INDEX IDX_BLOFPRDA_SNDBX_TEM_ID ON BLC_OFFER_PRICE_DATA (SNDBX_ORIG_ITEM_ID);
        CREATE INDEX IDX_BLOFPRDA_SNDBX_ORD_ID ON BLC_OFFER_PRICE_DATA (SNDBX_ORIG_RECORD_ID);
        CREATE INDEX IDX_BLOFPRDA_SNDBX_ID ON BLC_OFFER_PRICE_DATA (SNDBX_ID)
    </sql>
</changeSet>

Note: This is a changelog for Liquibase, if you are not using Liquibase, you will need to translate this accordingly for your database platform.

Event Triggers

We added a number of new BroadleafApplicationEvent triggers throughout the application. These event triggers are primarily listened to in order to send notifications, but your application could utilize them for other functionality.

Core

1. Order Confirmation (OrderSubmittedEvent)
2. Registration (RegisterCustomerEvent)
3. Forgot Password (ForgotPasswordEvent)
4. Forgot Username (ForgotUsernameEvent)
5. Admin Forgot Password (AdminForgotPasswordEvent)
6. Admin Forgot Username (AdminForgotUsernameEvent)
7. Contact Us (ContactUsEvent)

GiftCardAndCustomerCredit

1. Gift Card Submission (GiftCardEvent)

OMS

1. Order Block (OrderBlockEvent)
2. Order Change (OrderChangeEvent)
3. Order Cancelled (OrderCancelledEvent)
4. Fulfillment Order Fulfilled (FulfillmentOrderFulfilledEvent)
5. Fulfillment Order Cancelled (FulfillmentOrderCancelledEvent)
6. Return Authorization (ReturnAuthorizationEvent)
7. Return Confirmation (ReturnConfirmationEvent)

Quote

1. Quote Submitted (QuoteSubmittedEvent)
2. Quote Accepted (QuoteAcceptedEvent)
3. Quote Rejected (QuoteRejectedEvent)

Account

1. Order Rejected (OrderRejectedEvent)
2. Order Approved (OrderApprovedEvent)
3. Order Pending Approval (OrderPendingApprovalEvent)
4. Account Member Registration (RegisterAccountMemberEvent)

Enterprise

1. Promotion Success (PromotionSuccessEvent)
2. Promotion Failure (PromotionFailureEvent)
3. Scheduled Deploy Success (ScheduledDeploySuccessEvent)
4. Scheduled Deploy Failure (ScheduledDeployFailureEvent)

Marketplace

1. Create Vendor Fulfillment Orders (CreateVendorFulfillmentOrdersEvent)

Async Events

BroadleafApplicationEvent's by default are published and handled synchronously. However, in many systems, the publishing and the handling of the events should likely happen asynchronously. This way if there is an issue in the code consuming the event, the original workflow does not fail. There are a few steps in order to ensure these events are handled asynchronously.

1. Extend AbstractBroadleafApplicationEventListener and set isAsynchronous to return true.
2. Register a TaskExecutor bean with the name blApplicationEventMulticastTaskExecutor. This will result in that TaskExecutor being used to run the handler code asynchronously.

Another option to handle these events asynchronously is to utilize Broadleaf's ScheduledJobsAndEvents module. This is available for enterprise client's and instructions to utilize these jobs and events can be found in the module documentation.

Email

Part of this release includes significant changes to the internal APIs for handling emails. This includes the addition of a new service, NotificationDispatcher, which is now used instead of the deprecated EmailService. These changes were made in order to better support other types of notifications, such as SMS. In addition, the enterprise module, AdvancedCMS, now includes Email and SMS templating domain to allow admin management of notification metadata and content.

We tried to make the API changes backwards compatible as much as possible. If you are upgrading from 5.2 to 5.3 of Broadleaf, you will need to make some minor changes to ensure your existing emails still work.

Minimal Migration (keep things the same)

1. Set the emailType property on each of your EmailInfo beans to match the NotificationEventType, e.g. your order confirmation info would have the email type ORDER_CONFIRMATION.

2. The primary NotificationService bean used to handle a EmailNotification is blEmailNotificationService. When AdvancedCMS is included, this is of type EmailTemplateNotificationService; when it is not included, this is of type DefaultEmailNotificationService. To stick with the same email functionality as before, be sure this bean is overridden to be of type DefaultEmailNotificationService.

   @Bean
   public NotificationService blEmailNotificationService() {
       return new DefaultEmailNotificationService();
   }
   

3. Some of our internal email template names have changed. For instance, if the email template name was promote-success.html, it will now be promote_success.html. We advise those migrating to follow the same naming convention; lowercase and word-delimited by underscores.

4. EmailService is deprecated and we highly suggest any use of this service to be refactored to use NotificationDispatcher. This change is relatively straightforward.

   // BEFORE
   public void sendEmail(String email, EmailInfo emailInfo, Map<String, Object> props) {
       emailService.sendTemplateEmail(email, emailInfo, props);
   }
   
   // AFTER
   public void sendEmail(String email, EmailInfo emailInfo, Map<String, Object> props) {
       NotificationEventType type = NotificationEventType.getInstance(emailInfo.getType());
       try {
           notificationDispatcher.dispatchNotification(new EmailNotification(email, type, props));
       } catch (ServiceException e) {
           // LOG or handle error, typically happens when email fails to send
       }
   }
   

Email Template Migration

Part of this change requires renaming email templates to fit a common pattern. All email templates need to be lowercase and underscore delimited, e.g. orderConfirmation-email.html becomes order_confirmation_email.html. This pattern is definitely required for any internal Broadleaf email infos you are utilizing, and conditionally required for your own. In addition, if you are using AdvancedCMS and the new EmailTemplate domain, you will need to follow this template naming pattern.

If you are using the enterprise version of Broadleaf and have AdvancedCMS in your project, you will have the opportunity to leverage the new email template functionality. For instructions on how to utilize this functionality, please refer to the AdvancedCMS module documentation.

Adding New Email Notification

Sometimes you may want to add a new Notification to your application that we haven't already included. This is relatively straightforward if you follow these steps:

1. Create a new NotificationEventType bean

   @Component
   public MyNotificationEventType extends NotificationEventType {
   
       public static final NotificationEventType MY_NOTIFICATION = new NotificationEventType("MY_NOTIFICATION", "My Notification");
   }
   

2. Dispatch a new notification with that type

   @Autowired
   @Qualifier("blNotificationDispatcher")
   protected NotificationDispatcher notificationDispatcher;
   
   public void sendMyNotification(Customer customer) {
       try {
           Map<String, Object> context = new HashMap<>();
           context.put("customer", customer);
           notificationDispatcher.dispatchNotification(
               new EmailNotification(
                   customer.getEmailAddress(), 
                   MyNotificationEventType.MY_NOTIFICATION, 
                   context
               )
           );
       } catch(ServiceException e) {
           // handle error, probably just log something
       }
   }
   

3. Add the EmailInfo for this notification (or EmailTemplate if using AdvancedCMS)

   @Bean
   public EmailInfo myNotificationInfo() {
       EmailInfo emailInfo = new EmailInfo();
       emailInfo.setFromAddress("me@mycompany.com");
       emailInfo.setSubject("My Subject");
       emailInfo.setEmailType(MyNotificationEventType.MY_NOTIFICATION.getType());
       return emailInfo;
   }
   

Now the DefaultEmailNotificationService within NotificationDispatcher should pick up your EmailInfo and send that email when sendMyNotification is called.

Publishing Application Context Events

We have no added a new bean blApplicationEventPublisher of the class org.broadleafcommerce.common.event.BroadleafApplicationEventPublisherImpl for publishing application context events.
This should be used instead of the ApplicationContext for publishing events. This new service ensures that any event published in the middle of the transaction is not actually dispatched until
after the transaction has been completed. This is useful since many times you want to publish an event during a transactional operation, but you don't want the event to be handled asynchronously
before the transaction has closed and any data changes have been committed.