Module Installation

Steps to enable this module in your custom Broadleaf Commerce project

Steps

Step 1 Pull this dependency into your core/pom.xml:

<dependency>
    <groupId>com.broadleafcommerce</groupId>
    <artifactId>broadleaf-process</artifactId>
</dependency>

This assumes that you are using the Broadleaf BOM that pins all version information. If not, you will need to also add a <version> qualifier

Datasource Configuration

The Process module requires a new datasource be configured. This is done to ensure that systems using the Process API can offload their process traffic, if needed, to minimize impact to site performance.

Please note that if your project includes the ScheduledJobsAndEvents module, then this data source will also be used to manage all Scheduled Job and System Event related entities.

This datasource can be configured to point to the exact same schema as the blPU persistence unit for development and for low to medium volume installations. For installations with a large amount of admin users (tens of concurrently active users) or other heavy custom event usage, a separate physical database can be used.

Step 1 Configure the Persistence Unit

Here is an example blEventPU configuration for a MySQL installation. Add this to common-shared.properties in your core project.

   blEventPU.hibernate.hbm2ddl.auto=validate
   blEventPU.hibernate.dialect=org.hibernate.dialect.MySQL5InnoDBDialect
   blEventPU.hibernate.show_sql=false
   blEventPU.hibernate.cache.use_second_level_cache=false
   blEventPU.hibernate.cache.use_query_cache=false
   blEventPU.hibernate.hbm2ddl.import_files=null

Step 2 Add the Persistence Unit to the Application

Add the following line to persistence-core.xml in the core project:

   <persistence-unit name="blEventPU" transaction-type="RESOURCE_LOCAL">
       <non-jta-data-source>jdbc/event</non-jta-data-source>
       <exclude-unlisted-classes/>
   </persistence-unit>

The key item here is the non-jta-data-source name, which should match the datasource configured in your container. Please refer to your container documentation for instructions on configuring a jdbc datasource.

Step 3 Configure the Datasource in the Application

Add the following line to applicationContext-datasource.xml in both admin and site:

   <jee:jndi-lookup id="webEventDS" jndi-name="jdbc/event"/>

You'll find the other datasource entries such as "webDS" already in this file.

Step 4 Register the Datasource with Broadleaf

Add the following to the sourceMap property of blMergedDataSources in both applicationContext.xml in site and applicationContext-admin.xml in admin:

   <entry key="jdbc/event" value-ref="webEventDS"/>

Schema Changes

To add all of the necessary database tables and columns for this module, please follow the Liquibase update documentation.

Admin Security Changes

The data in the following SQL file is required to establish Admin sections and permissions for this module:

classpath:/config/bc/sql/load_process_admin_security.sql

This file is automatically included if you have set blPU.hibernate.hbm2ddl.auto=create and you have not set import.sql.enabled=false in your properties files. If you are not using Hibernate's auto DDL process and are using Liquibase, you can add a new changeSet that references this file:

<?xml version="1.1" encoding="UTF-8" standalone="no"?>
<databaseChangeLog xmlns="http://www.liquibase.org/xml/ns/dbchangelog" xmlns:ext="http://www.liquibase.org/xml/ns/dbchangelog-ext" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog-ext http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-ext.xsd http://www.liquibase.org/xml/ns/dbchangelog http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-3.5.xsd">
    <changeSet author="broadleaf" id="some-unique-id">
        <sqlFile path="config/bc/sql/load_process_admin_security.sql" encoding="utf8" stripComments="true" />
    </changeSet>
</databaseChangeLog>

Finally, you can unpack the downloaded .jar file and look at the files in the config/bc/sql folder to execute this sql manually.

Application Context Updates

applicationContext-admin-filter.xml Updates Non-Spring Boot Projects

Since processes can be visualized and managed through the Admin interface, the following updates are needed to supply a blEventPU-based entity manager throughout the request scope.

Note: With the introduction of this functionality, you may see a slightly increased load on your jdbc/event database resource, which may require an increase in the connection pool size.

1. Update admin/src/main/webapp/WEB-INF/applicationContext-admin-filter.xml to include the following bean:

   <bean id="openEventEntityManagerInViewFilter" class="org.springframework.orm.jpa.support.OpenEntityManagerInViewFilter">
       <property name="entityManagerFactoryBeanName" value="blEntityManagerFactoryEventInfo"/>
   </bean>
   

2. Then include the bean in your blPreSecurityFilterChain definition as follows:

   <bean id="blPreSecurityFilterChain" class="org.springframework.security.web.FilterChainProxy">
       <sec:filter-chain-map request-matcher="ant">
           <sec:filter-chain pattern="/**" filters="
              ...
              openEntityManagerInViewFilter,
              openEventEntityManagerInViewFilter,
              ..."/>
       </sec:filter-chain-map>
   </bean>
   

Note: If you have a Spring Boot based project, then these steps are not necessary because the filter will already be configured. Additionally, the filter will be automatically ordered according to the order provided on its bean definition.