Documentation Home
Changelog

2.3 to 3.0 Migration

Exhaustive diff of changes

If you are currently targeting the 2.3.0-M3 or below, you will need to make the following workflow changes.

Workflows

Full, updated documentation on workflows is located at Workflows and Activities. This has actually made your custom configuration much simpler, as you no longer need to redeclare the entire Broadleaf workflow just to add a single activity. Instead, simply change the ordering of your activity.

For instance, you might have overridden the blAddItemWorkflow to execute some sort of analytics. You might find something like this in your applicationContext:

<bean id="blAddItemWorkflow" class="org.broadleafcommerce.core.workflow.SequenceProcessor">
    <property name="processContextFactory">
        <bean class="org.broadleafcommerce.core.order.service.workflow.CartOperationProcessContextFactory"/>
    </property>
    <property name="activities">
        <list>
            <bean class="org.broadleafcommerce.core.order.service.workflow.add.ValidateAddRequestActivity"/>

            <!-- Custom activity for analytics -->
            <bean class="com.mycompany.core.workflow.AddToAnalyticsActivity"/>

            <bean class="org.broadleafcommerce.core.order.service.workflow.add.AddOrderItemActivity"/>
            <bean class="org.broadleafcommerce.core.order.service.workflow.add.AddFulfillmentGroupItemActivity"/>
            <bean class="org.broadleafcommerce.core.order.service.workflow.PriceOrderIfNecessaryActivity"/>
            <bean class="org.broadleafcommerce.core.order.service.workflow.VerifyFulfillmentGroupItemsActivity"/>
        </list>
    </property>
    <property name="defaultErrorHandler" ref="blDefaultErrorHandler"/>
</bean>

Since these lists are now merged, if you were to start up the application you would get duplicates of the framework activities, all ordered at the end of the workflow. In the new way to configure workflows, the above definition would simplify to:

<bean id="blAddItemWorkflow" class="org.broadleafcommerce.core.workflow.SequenceProcessor">
   <property name="activities">
        <list>           
            <!-- Custom activity for analytics -->
            <!-- Explicitly specify the ordering to occur between the first and second activity -->
            <bean p:order="1500" class="com.mycompany.core.workflow.AddToAnalyticsActivity"/>
        </list>
    </property>
</bean>

*Important Note:* don't forget to specify orderings for your activities if they need to occur in-between framework activities. If you do not explicitly specify an order, your activity will be placed at the end of the workflow (more explicitly, the default order is Ordered.LOWEST_PRECEDENCE).

Maven Updates

Update the root pom.xml

(sample: https://github.com/BroadleafCommerce/DemoSite/blob/broadleaf-3.0.0-GA/pom.xml)

  1. While it may be introduced again in the future, the combined module is not currently supported in 3.0.
    • In the root pom.xml, remove the line <module>combined</module> from the "modules" element.
  2. Change the blc.version element to 3.0.0-SNAPSHOT <blc.version>3.0.0-SNAPSHOT</blc.version>
  3. Remove the gwt.version element (phased out) <gwt.version>2.4.0</gwt.version>
  4. If not present already, add a public snapshots repository to retrieve BLC snapshot builds. xml <repositories> <repository> <id>public snapshots</id> <name>public snapshots</name> <url>http://nexus.broadleafcommerce.org/nexus/content/repositories/snapshots/</url> </repository> </repositories>
  5. Update jrebel plugin dependency
    • change all instances of <artifactId>javarebel-maven-plugin</artifactId> to <artifactId>jrebel-maven-plugin</artifactId>
    • change the jrebel plugin version to 1.1.3
  6. Remove gwt maven plugin config (phased out) xml <plugin> <groupId>org.codehaus.mojo</groupId> <artifactId>gwt-maven-plugin</artifactId> <version>${gwt.version}</version> </plugin>
  7. Remove the following unwanted, or unnecessary dependency elements
    • groupId: com.google.gwt / artifactId: gwt-user
    • groupId: org.hibernate / artifactId: hibernate-validator-annotation-processor
    • groupId: javax.validation / artifactId: validation-api

Update admin/pom.xml

(sample: https://github.com/BroadleafCommerce/DemoSite/blob/broadleaf-3.0.0-GA/admin/pom.xml)

  1. Remove the following unwanted, or unnecessary plugins
    • groupId: org.apache.maven.plugins / artifactId: maven-source-plugin
    • groupId: org.codehaus.mojo / artifactId: gwt-maven-plugin
    • groupId: org.apache.maven.plugins / artifactId: maven-clean-plugin
  2. Remove the following unwanted, or unnecessary profiles
    • id: gwt-jrebel
    • id: full-clean
  3. Remove the following unwanted, or unnecessary dependency elements
    • groupId: org.hibernate / artifactId: hibernate-validator-annotation-processor
    • groupId: javax.validation / artifactId: validation-api
  4. Update jrebel plugin dependency
    • change all instances of <artifactId>javarebel-maven-plugin</artifactId> to <artifactId>jrebel-maven-plugin</artifactId>

Update site/pom.xml

(sample: https://github.com/BroadleafCommerce/DemoSite/blob/broadleaf-3.0.0-GA/site/pom.xml)

  1. Update jrebel plugin dependency
    • change all instances of <artifactId>javarebel-maven-plugin</artifactId> to <artifactId>jrebel-maven-plugin</artifactId>

Update core/pom.xml

(sample: https://github.com/BroadleafCommerce/DemoSite/blob/broadleaf-3.0.0-GA/core/pom.xml)

  1. Update jrebel plugin dependency
    • change all instances of <artifactId>javarebel-maven-plugin</artifactId> to <artifactId>jrebel-maven-plugin</artifactId>

Site and Admin

Update all applicationContext*.xml files

  1. Look in site/src/main/webapp/WEB-INF, admin/src/main/webapp/WEB-INF and core/src/main/resources
  2. Change all spring schemaLocation attribute values to point to 3.2 (e.g. spring-jee-3.1.xsd should point to spring-jee-3.2.xsd)
    • Except for spring-security-3.1.xsd, which should be left at version 3.1

Admin Updates

We have completely revamped our entire admin in Broadleaf 3.0 by moving from GWT to a Spring MVC application. If you have done any customizations to the frontend, GWT-version of the admin, you will likely have to make those changes again. That said, the server-side of the admin is largely similar (Custom Persistence Handlers, Persistence Modules, etc) so if you have made changes there it is likely that they will still work. We recommend verifying this.

web.xml

  1. Add the application-filter application context
    • add /WEB-INF/applicationContext-admin-filter.xml immediately before /WEB-INF/applicationContext-admin.xml in the <param-value> element for <param-name>patchConfigLocation</param-name>
  2. Remove the following <filter> definitions, as they are now declared in applicationContext-filter.xml
    • filter-name: entityManagerInViewFilter
    • filter-name: blAdminSandBoxFilter
    • filter-name: blPrecompressedArtifactsFilter
  3. Remove the following <filter-mapping. definitions as well
    • filter-name: entityManagerInViewFilter
    • filter-name: blAdminSandBoxFilter
    • filter-name: blPrecompressedArtifactsFilter
  4. Add a new <filter> element for "pre-security" filters (see below). This <filter> should appear before the <filter> declaration for <filter-name>springSecurityFilterChain</filter-name> xml <filter> <filter-name>blPreSecurityFilterChain</filter-name> <filter-class>org.springframework.web.filter.DelegatingFilterProxy</filter-class> </filter>
  5. Add a new <filter> element for "post-security" filters (see below). This <filter> should appear after the <filter> declaration for <filter-name>springSecurityFilterChain</filter-name> xml <filter> <filter-name>blPostSecurityFilterChain</filter-name> <filter-class>org.springframework.web.filter.DelegatingFilterProxy</filter-class> </filter>
  6. Add a new <filter-mapping> element for "pre-security" (see below). This <filter-mapping> should appear before the <filter-mapping> declaration for <filter-name>springSecurityFilterChain</filter-name> xml <filter-mapping> <filter-name>blPreSecurityFilterChain</filter-name> <url-pattern>/*</url-pattern> </filter-mapping>
  7. Add a new <filter-mapping> element for "post-security" (see below). This <filter-mapping> should appear after the <filter-mapping> declaration for <filter-name>springSecurityFilterChain</filter-name> xml <filter-mapping> <filter-name>blPostSecurityFilterChain</filter-name> <url-pattern>/*</url-pattern> </filter-mapping>
  8. Remove the following unwanted <servlet> and <servlet-mapping> elements
    • servlet-name: remoteLogging
  9. Remove "admin.html" as a <welcome-file> element

Update admin/src/main/webapp/WEB-INF/applicationContext-admin.xml

(sample: https://github.com/BroadleafCommerce/DemoSite/blob/broadleaf-3.0.0-GA/admin/src/main/webapp/WEB-INF/applicationContext-admin.xml)

  1. Add externalized string support by including the "messageSource" bean: xml <bean id="messageSource" class="org.broadleafcommerce.common.util.BroadleafMergeResourceBundleMessageSource"> <property name="useCodeAsDefaultMessage" value="${messages.useCodeAsDefaultMessage}" /> <property name="cacheSeconds" value="${messages.cacheSeconds}" /> <property name="basenames"> <list> <value>classpath:messages-admin</value> </list> </property> </bean>

Update admin/src/main/webapp/WEB-INF/applicationContext-admin-security.xml

(sample: https://github.com/BroadleafCommerce/DemoSite/blob/broadleaf-3.0.0-GA/admin/src/main/webapp/WEB-INF/applicationContext-admin-security.xml)

  1. Replace <sec:http> elements for ignoring security for static elements and "forgot password" flows. Use the following:

    <sec:http pattern="/**/*.css" security="none" />
<sec:http pattern="/**/*.js" security="none" />
<sec:http pattern="/img/**" security="none" />
<sec:http pattern="/favicon.ico" security="none" />
<sec:http pattern="/robots.txt" security="none" />
<sec:http pattern="/login" security="none" />
<sec:http pattern="/forgotUsername" security="none" />
<sec:http pattern="/forgotPassword" security="none" />
<sec:http pattern="/changePassword" security="none" />
<sec:http pattern="/resetPassword" security="none" />
<sec:http pattern="/sendResetPassword" security="none" />

  2. Replace the <sec:logout> element with the following. The logout-url and logout-success-url attributes have changed.

    <sec:logout invalidate-session="true" logout-url="/adminLogout.htm" logout-success-url="/login"/>

  3. Update the <sec:intercept-url> elements for "blAdminFilterSecurityInterceptor` to the following. The patterns have changed.

    <sec:intercept-url pattern="/**/*" access="PERMISSION_OTHER_DEFAULT" />
<sec:intercept-url pattern="/*" access="PERMISSION_OTHER_DEFAULT" />

Replace admin/src/main/webapp/WEB-INF/applicationContext-servlet-admin.xml

  1. Download from https://github.com/BroadleafCommerce/DemoSite/blob/broadleaf-3.0.0-GA/admin/src/main/webapp/WEB-INF/applicationContext-servlet-admin.xml
  2. Replace admin/src/main/webapp/WEB-INF/applicationContext-servlet-admin.xml with the downloaded file

Add the new admin/src/main/webapp/WEB-INF/applicationContext-admin-filter.xml file

  1. Download from https://github.com/BroadleafCommerce/DemoSite/blob/broadleaf-3.0.0-GA/admin/src/main/webapp/WEB-INF/applicationContext-admin-filter.xml

Site/Frontend Updates

Update site/src/main/webapp/WEB-INF/applicationContext-filter.xml

(sample: https://github.com/BroadleafCommerce/DemoSite/blob/broadleaf-3.0.0-GA/site/src/main/webapp/WEB-INF/web.xml)

  1. Add the blTranslationFilter to blPostSecurityFilterChain. The final definition should look like:

    <bean id="blPostSecurityFilterChain" class="org.springframework.security.web.FilterChainProxy">
    <sec:filter-chain-map request-matcher="ant">
        <sec:filter-chain pattern="/**" filters="
            blURLHandlerFilter,
            blTranslationFilter,
            blCartStateFilter"/>
    </sec:filter-chain-map>
</bean>

Update site/src/main/webapp/WEB-INF/applicationContext-servlet.xml

https://github.com/BroadleafCommerce/DemoSite/blob/broadleaf-3.0.0-GA/site/src/main/webapp/WEB-INF/applicationContext-servlet.xml

  1. Remove js and css resources mappings. Delete the following:

    <mvc:resources order="-10" location="/css/" mapping="/css/**" />
<mvc:resources order="-10" location="/js/" mapping="/js/**" />

  2. Add mappings for JS and CSS resources by adding the following:

    <bean id="blJsResources" class="org.broadleafcommerce.common.web.resource.BroadleafResourceHttpRequestHandler">
    <property name="locations">
        <list>
            <value>/js/</value>
            <value>classpath:/common_js/</value>
        </list>
    </property>
</bean>




/css/


<!-- Map various location URLs to our resource handlers -->




blJsResources
blCssResources



```

Update site/src/main/webapp/WEB-INF/applicationContext.xml

https://github.com/BroadleafCommerce/DemoSite/blob/broadleaf-3.0.0-GA/site/src/main/webapp/WEB-INF/applicationContext.xml

  1. Replace the messageSource bean definition with the following (if you have added any messages to this, they will need to have classpath: prepending to them):

    <bean id="messageSource" class="org.broadleafcommerce.common.util.BroadleafMergeResourceBundleMessageSource">
    <property name="basenames">
         <list>
             <value>classpath:messages</value>
         </list>
    </property>
</bean>

  2. Add image thumbnail support:

    <bean id="blStaticMapNamedOperationComponent" class="org.broadleafcommerce.cms.file.service.operation.StaticMapNamedOperationComponent">
    <property name="namedOperations">
        <map>
            <entry key="browse">
                <map>
                    <entry key="resize-width-amount" value="400"/>
                    <entry key="resize-height-amount" value="400"/>
                    <entry key="resize-high-quality" value="false"/>
                    <entry key="resize-maintain-aspect-ratio" value="true"/>
                    <entry key="resize-reduce-only" value="true"/>
                </map>
            </entry>
            <entry key="thumbnail">
                <map>
                    <entry key="resize-width-amount" value="60"/>
                    <entry key="resize-height-amount" value="60"/>
                    <entry key="resize-high-quality" value="false"/>
                    <entry key="resize-maintain-aspect-ratio" value="true"/>
                    <entry key="resize-reduce-only" value="true"/>
                </map>
            </entry>
        </map>
    </property>
</bean>

Other Updates

A custom AdminLoginController (extends BroadleafAdminLoginController) is no longer required. Remove such a class if you've implemented one.

Update Solr configuration (if using Solr search)

  1. Update site/resources/schema.xml
  2. If you have customized Solr indexing configuration, then review your changes before performing any update here

  3. Replace the <fields> element with the following:

    <fields>
<field name="namespace" type="string" indexed="true" stored="false" />
<field name="id" type="string" indexed="true" stored="true" />
<field name="productId" type="long" indexed="true" stored="true" />
<field name="category" type="long" indexed="true" stored="false" multiValued="true" />
<field name="explicitCategory" type="long" indexed="true" stored="false" multiValued="true" />
<field name="searchable" type="text_general" indexed="true" stored="false" />
<dynamicField name="*_searchable" type="text_general" indexed="true" stored="false" />

<dynamicField name="*_i" type="int" indexed="true" stored="false" />
<dynamicField name="*_is" type="int" indexed="true" stored="false" multiValued="true" />
<dynamicField name="*_s" type="string" indexed="true" stored="false" />
<dynamicField name="*_ss" type="string" indexed="true" stored="false" multiValued="true" />
<dynamicField name="*_l" type="long" indexed="true" stored="false" />
<dynamicField name="*_ls" type="long" indexed="true" stored="false" multiValued="true" />
<dynamicField name="*_t" type="text_general" indexed="true" stored="false" />
<dynamicField name="*_txt" type="text_general" indexed="true" stored="false" multiValued="true" />
<dynamicField name="*_b" type="boolean" indexed="true" stored="false" />
<dynamicField name="*_bs" type="boolean" indexed="true" stored="false" multiValued="true" />
<dynamicField name="*_d" type="double" indexed="true" stored="false" />
<dynamicField name="*_ds" type="double" indexed="true" stored="false" multiValued="true" />
<dynamicField name="*_p" type="double" indexed="true" stored="false" />

<dynamicField name="*_dt" type="date" indexed="true" stored="false" />
<dynamicField name="*_dts" type="date" indexed="true" stored="false" multiValued="true" />

<!-- some trie-coded dynamic fields for faster range queries -->
<dynamicField name="*_ti" type="tint" indexed="true" stored="false" />
<dynamicField name="*_tl" type="tlong" indexed="true" stored="false" />
<dynamicField name="*_td" type="tdouble" indexed="true" stored="false" />
<dynamicField name="*_tdt" type="tdate" indexed="true" stored="false" />
</fields>

Database Changes

You can find the history of changes to the database in the [[Database-Model]].

You can run the following script AT YOUR OWN RISK to update your tables.

alter table BLC_ADDRESS add column ADDRESS_LINE3 varchar(255);
alter table BLC_ADMIN_SECTION add column CEILING_ENTITY varchar(255);
alter table BLC_ADMIN_SECTION add column DISPLAY_ORDER integer;
create table BLC_CATALOG (CATALOG_ID bigint not null, NAME varchar(255), primary key (CATALOG_ID));
alter table BLC_CATEGORY add column TAX_CODE varchar(255);
alter table BLC_CUSTOMER add column TAX_EXEMPTION_CODE varchar(255);
alter table BLC_FULFILLMENT_OPTION add column TAX_CODE varchar(255);
alter table BLC_FULFILLMENT_OPTION add column TAXABLE boolean;
alter table BLC_LOCALE add column IS_TRANSLATABLE boolean;
create table BLC_MODULE_CONFIGURATION (MODULE_CONFIG_ID bigint not null, CREATED_BY bigint, DATE_CREATED timestamp, DATE_UPDATED timestamp, UPDATED_BY bigint, CONFIG_TYPE varchar(255) not null, IS_ACTIVE boolean not null, IS_DEFAULT boolean not null, MODULE_NAME varchar(255) not null, primary key (MODULE_CONFIG_ID));
alter table BLC_OFFER add column AUTOMATICALLY_ADDED boolean;
alter table BLC_PRODUCT add column TAX_CODE varchar(255);
alter table BLC_PRODUCT_OPTION add column ERROR_CODE varchar(255);
alter table BLC_PRODUCT_OPTION add column ERROR_MESSAGE varchar(255);
alter table BLC_PRODUCT_OPTION add column VALIDATION_TYPE varchar(255);
alter table BLC_PRODUCT_OPTION add column USE_IN_SKU_GENERATION boolean;
alter table BLC_PRODUCT_OPTION add column VALIDATION_STRING varchar(255);
alter table BLC_SITE add column ARCHIVED char(255);
alter table BLC_SITE add column DEACTIVATED boolean;
create table BLC_SITE_CATALOG (CATALOG_ID bigint not null, SITE_ID bigint not null);
alter table BLC_SKU add column TAX_CODE varchar(255);
alter table BLC_SKU add column CURRENCY_CODE varchar(255);
alter table BLC_STATIC_ASSET add column ALT_TEXT varchar(255);
alter table BLC_STATIC_ASSET add column STORAGE_TYPE varchar(255);
alter table BLC_STATIC_ASSET add column TITLE varchar(255);
alter table BLC_TAX_DETAIL add column TAX_COUNTRY varchar(255);
alter table BLC_TAX_DETAIL add column JURISDICTION_NAME varchar(255);
alter table BLC_TAX_DETAIL add column TAX_REGION varchar(255);
alter table BLC_TAX_DETAIL add column TAX_NAME varchar(255);
alter table BLC_TAX_DETAIL add column MODULE_CONFIG_ID bigint;
create table BLC_TRANSLATION (TRANSLATION_ID bigint not null, ENTITY_ID varchar(255), ENTITY_TYPE varchar(255), FIELD_NAME varchar(255), LOCALE_CODE varchar(255), TRANSLATED_VALUE clob(2147483646), primary key (TRANSLATION_ID));
alter table BLC_SITE_CATALOG add constraint FK5F3F2047843A8B63 foreign key (SITE_ID) references BLC_SITE;
alter table BLC_SITE_CATALOG add constraint FK5F3F2047A350C7F1 foreign key (CATALOG_ID) references BLC_CATALOG;
alter table BLC_SKU add constraint FK28E82CF73E2FC4F9 foreign key (CURRENCY_CODE) references BLC_CURRENCY;
alter table BLC_TAX_DETAIL add constraint FKEABE4A4BC50D449 foreign key (MODULE_CONFIG_ID) references BLC_MODULE_CONFIGURATION;
create index ENTITY_TYPE_INDEX on BLC_TRANSLATION (ENTITY_TYPE);
```## Database Changes

You can find the history of changes to the database in the [[Database-Model]].

You can run the following script **AT YOUR OWN RISK** to update your tables.

```sql
alter table BLC_ADDRESS add column ADDRESS_LINE3 varchar(255);
alter table BLC_ADMIN_SECTION add column CEILING_ENTITY varchar(255);
alter table BLC_ADMIN_SECTION add column DISPLAY_ORDER integer;
create table BLC_CATALOG (CATALOG_ID bigint not null, NAME varchar(255), primary key (CATALOG_ID));
alter table BLC_CATEGORY add column TAX_CODE varchar(255);
alter table BLC_CUSTOMER add column TAX_EXEMPTION_CODE varchar(255);
alter table BLC_FULFILLMENT_OPTION add column TAX_CODE varchar(255);
alter table BLC_FULFILLMENT_OPTION add column TAXABLE boolean;
alter table BLC_LOCALE add column IS_TRANSLATABLE boolean;
create table BLC_MODULE_CONFIGURATION (MODULE_CONFIG_ID bigint not null, CREATED_BY bigint, DATE_CREATED timestamp, DATE_UPDATED timestamp, UPDATED_BY bigint, CONFIG_TYPE varchar(255) not null, IS_ACTIVE boolean not null, IS_DEFAULT boolean not null, MODULE_NAME varchar(255) not null, primary key (MODULE_CONFIG_ID));
alter table BLC_OFFER add column AUTOMATICALLY_ADDED boolean;
alter table BLC_PRODUCT add column TAX_CODE varchar(255);
alter table BLC_PRODUCT_OPTION add column ERROR_CODE varchar(255);
alter table BLC_PRODUCT_OPTION add column ERROR_MESSAGE varchar(255);
alter table BLC_PRODUCT_OPTION add column VALIDATION_TYPE varchar(255);
alter table BLC_PRODUCT_OPTION add column USE_IN_SKU_GENERATION boolean;
alter table BLC_PRODUCT_OPTION add column VALIDATION_STRING varchar(255);
alter table BLC_SITE add column ARCHIVED char(255);
alter table BLC_SITE add column DEACTIVATED boolean;
create table BLC_SITE_CATALOG (CATALOG_ID bigint not null, SITE_ID bigint not null);
alter table BLC_SKU add column TAX_CODE varchar(255);
alter table BLC_SKU add column CURRENCY_CODE varchar(255);
alter table BLC_STATIC_ASSET add column ALT_TEXT varchar(255);
alter table BLC_STATIC_ASSET add column STORAGE_TYPE varchar(255);
alter table BLC_STATIC_ASSET add column TITLE varchar(255);
alter table BLC_TAX_DETAIL add column TAX_COUNTRY varchar(255);
alter table BLC_TAX_DETAIL add column JURISDICTION_NAME varchar(255);
alter table BLC_TAX_DETAIL add column TAX_REGION varchar(255);
alter table BLC_TAX_DETAIL add column TAX_NAME varchar(255);
alter table BLC_TAX_DETAIL add column MODULE_CONFIG_ID bigint;
create table BLC_TRANSLATION (TRANSLATION_ID bigint not null, ENTITY_ID varchar(255), ENTITY_TYPE varchar(255), FIELD_NAME varchar(255), LOCALE_CODE varchar(255), TRANSLATED_VALUE clob(2147483646), primary key (TRANSLATION_ID));
alter table BLC_SITE_CATALOG add constraint FK5F3F2047843A8B63 foreign key (SITE_ID) references BLC_SITE;
alter table BLC_SITE_CATALOG add constraint FK5F3F2047A350C7F1 foreign key (CATALOG_ID) references BLC_CATALOG;
alter table BLC_SKU add constraint FK28E82CF73E2FC4F9 foreign key (CURRENCY_CODE) references BLC_CURRENCY;
alter table BLC_TAX_DETAIL add constraint FKEABE4A4BC50D449 foreign key (MODULE_CONFIG_ID) references BLC_MODULE_CONFIGURATION;
create index ENTITY_TYPE_INDEX on BLC_TRANSLATION (ENTITY_TYPE);