Chapter 12. Integrating Red Hat JBoss BPM Suite with Red Hat JBoss Fuse

Red Hat JBoss Fuse integration allows users of Red Hat JBoss Fuse to complement their integration solution with additional features provided by Red Hat JBoss BPM Suite and Red Hat JBoss BRMS.

Red Hat JBoss BPM Suite integration is provided by two features.xml files:

  • drools-karaf-features-VERSION-features.xml

    This file provides core Red Hat JBoss BPM Suite and Red Hat JBoss BRMS features, which defines the OSGi features that can be deployed into Red Hat JBoss Fuse. This file is a part of the Red Hat JBoss BPM Suite and Red Hat JBoss BRMS product. OSGi users can install features from this file in order to install Red Hat JBoss BRMS engine or Red Hat JBoss BPM Suite engine into Red Hat JBoss Fuse and use it in their applications.

  • karaf-features-VERSION-features.xml

    This file provides additional features used for integrating Red Hat JBoss BPM Suite and Red Hat JBoss BRMS with Apache Camel, primarily in Red Hat JBoss Fuse. This file is part of the Integration Pack and it defines OSGi features that enable integration with Apache Camel and SwitchYard. In addition to the karaf-features XML file, the Integration Pack also contains a features.xml file for quick starts.

  • drools-karaf-features-VERSION-features-fuse-6_3.xml

    This file is used for integration of Red Hat JBoss BPM Suite with Red Hat JBoss Fuse 6.3.0.

For further information about integration of Red Hat JBoss BPM Suite with Red Hat JBoss Fuse, see the Install Integration Pack chapter of the Red Hat JBoss Fuse Integration Guide.

12.1. Core Red Hat JBoss BPM Suite and Red Hat JBoss BRMS Features

Core Red Hat JBoss BPM Suite and Red Hat JBoss BRMS features are provided by one of the following files:

  • For integration with Red Hat JBoss Fuse 6.2.1, use the drools-karaf-features-VERSION-features.xml file.

  • For integration with Red Hat JBoss Fuse 6.3.0, use the drools-karaf-features-VERSION-features-fuse-6_3.xml file

    VERSION is the version of Red Hat JBoss BPM Suite you are using, for example 6.5.0.Final-redhat-9. See the Supported Component Versions chapter of the Red Hat JBoss BPM Suite Installation Guide.

The files are present in the product Maven repository (org/drools/drools-karaf-features) or the jboss-brms-bpmsuite-VERSION-redhat-VERSION-fuse-features.zip file. These files provide the following features:

  • drools-common
  • drools-module
  • drools-templates
  • drools-decisiontable
  • drools-jpa
  • kie
  • kie-ci
  • kie-spring
  • kie-aries-blueprint
  • jbpm-commons
  • jbpm-human-task
  • jbpm
  • droolsjbpm-hibernate
  • h2

The following table provides example of use cases for some of the features listed above.

Table 12.1. Features and Use Case Examples

FeatureUse Case

drools-module

Use the Red Hat JBoss BRMS engine for rules evaluation, without requiring persistence, processes, or decision tables.

drools-jpa

Use the Red Hat JBoss BRMS engine for rules evaluation with persistence and transactions, but without requiring processes or decision tables. The drools-jpa feature already includes drools-module, however you may also need to install the droolsjbpm-hibernate feature, or ensure there is a compatible hibernate bundle installed.

drools-decisiontable

Use the Red Hat JBoss BRMS engine with decision tables.

jbpm

Use the Red Hat JBoss BPM Suite (or Red Hat JBoss BRMS engine with processes). The jbpm feature already includes drools-module and drools-jpa. You may also need to install the droolsjbpm-hibernate feature, or ensure that there is a compatible hibernate bundle installed.

jbpm and jbpm-human-task

Use the Red Hat JBoss BPM Suite (or Red Hat JBoss BRMS engine with processes) with Human Task.

core engine JARs and kie-ci

Use Red Hat JBoss BRMS or Red Hat JBoss BPM Suite with KieScanner (KIE-CI) to download kJARs from a Maven repository.

kie-spring

Use KIE-Spring integration. See the section called “kie-spring Feature Further Information” for more information.

kie-spring and kie-aries-blueprint

Use KIE-Aries-Blueprint integration.

kie-spring Feature Further Information

  • Use org.drools.osgi.spring.OsgiKModuleBeanFactoryPostProcessor instead of org.kie.spring.KModuleBeanFactoryPostProcessor to postprocess KIE elements in an OSGi environment.

  • Do not install the drools-module feature before the kie-spring feature. Otherwise, the drools-compiler bundle does not detect packages exported by kie-spring.

    Run osgi:refresh drools-compiler_bundle_ID if you have installed the features in the incorrect order to force drools-compiler to rebuild its Import-Package metadata.

12.2. Additional Features for SwitchYard and Apache Camel Integration

The following additional features for integration with SwitchYard and Apache Camel on Red Hat JBoss Fuse are provided by the integration pack:

  • fuse-bxms-switchyard-common-knowledge
  • fuse-bxms-switchyard-rules
  • fuse-bxms-switchyard-bpm
  • kie-camel
  • jbpm-workitems-camel

The integration pack features are defined in the karaf-features-VERSION-features.xml file. This file (and supporting repositories) is located in http://repository.jboss.org/nexus/content/repositories/public, which is already configured for use on Red Hat JBoss Fuse out of the box in INSTALLATION_DIRECTORY/etc/org.ops4j.pax.url.mvn.cfg.

The file can also be downloaded from either the Red Hat JBoss Fuse product page or Red Hat JBoss BPM Suite product page on the Red Hat Customer Portal.

12.3. Installing and Updating Core Integration Features

Note

This section refers to features in the drools-karaf-features-VERSION-features.xml file. For additional integration features, see Section 12.4, “Installing Additional Integration Features”.

If you have already installed an older version of the core Red Hat JBoss BPM Suite and Red Hat JBoss BRMS features (for example, drools-karaf-features-6.2.0.Final-redhat-6-features.xml), you need to remove them and all associated files before installing the most recent features.xml file.

Procedure: Removing Existing drools-karaf-features Installation

  1. Start the Red Hat JBoss Fuse console using: 

    $ ./INSTALLATION_DIRECTORY/bin/fuse

  2. Unistall old features or applications that used the previous features.xml file. For example: 

    JBossFuse:karaf@root> features:uninstall drools-module
JBossFuse:karaf@root> features:uninstall jbpm
JBossFuse:karaf@root> features:uninstall kie-ci

  3. Search for references of bundles using drools, kie, or jbpm, and remove them: 

    karaf@root> list -t 0 -s | grep drools
karaf@root> list -t 0 -s | grep kie
karaf@root> list -t 0 -s | grep jbpm

    To remove the bundles: 

    karaf@root> osgi:uninstall BUNDLE_ID

  4. Remove the old drools-karaf-features URL: 

    karaf@root> features:removeurl mvn:org.drools/drools-karaf-features/6.2.0.Final-redhat-VERSION/xml/features
  5. Restart Red Hat JBoss Fuse.

To install the drools-karaf-features:

Procedure: Installing Core Red Hat JBoss BPM Suite and Red Hat JBoss BRMS Features

  1. Configure required repositories:

    • Edit the INSTALLATION_DIRECTORY/etc/org.ops4j.pax.url.mvn.cfg file in your Red Hat JBoss Fuse installation and add the following entry to the org.ops4j.pax.url.mvn.repositories variable (note that entries are separated by , \):

  2. Start Red Hat JBoss Fuse: 

    $ ./INSTALLATION_DIRECTORY/bin/fuse

  3. Add a reference to the core features file by running the following console command:

    For Red Hat JBoss Fuse 6.2.1, use: 

    JBossFuse:karaf@root> features:addurl mvn:org.drools/drools-karaf-features/VERSION/xml/features

    For Red Hat JBoss Fuse 6.3.0, use: 

    JBossFuse:karaf@root> features:addurl mvn:org.drools/drools-karaf-features/VERSION/xml/features-fuse-6_3

    For example: 

    features:addurl mvn:org.drools/drools-karaf-features/6.4.0.Final-redhat-10/xml/features-fuse-6_3

    To see the current drools-karaf-features version, see the Supported Component Versions chapter of the Red Hat JBoss BPM Suite Installation Guide.

  4. You can now install the features provided by this file by running, for example, the following console command: 

    JBossFuse:karaf@root> features:install jbpm

12.4. Installing Additional Integration Features

Use the following procedure for additional integration with SwitchYard and Apache Camel.

Procedure: SwitchYard and Apache Camel Integration

  1. Download the fuse-integration package that is aligned with your version of Red Hat JBoss Fuse.

    Note

    For instance, if you want to use the 6.2.0.redhat-117 version of Red Hat JBoss Fuse, you need to install the fuse-6.2.0.redhat-117 Red Hat JBoss Fuse integration features.

  2. Add the remote Maven repository that contains the fuse dependencies to your karaf instance:

    • Edit FUSE_HOME/etc/org.ops4j.pax.url.mvn.cfg

  3. Update the Drools features URL: 

    JBossFuse:karaf@root> features:addurl mvn:org.switchyard.karaf/mvn:org.switchyard.karaf/switchyard/SWITCHYARD_VERSION/xml/core-features
JBossFuse:karaf@root> features:addurl mvn:org.jboss.integration.fuse/karaf-features/1.0.0.redhat-VERSION/xml/features

    Additionally, update the drools-karaf-features URL. For Red Hat JBoss Fuse 6.2.1, use: 

    JBossFuse:karaf@root> features:addurl mvn:org.drools/drools-karaf-features/VERSION/xml/features

    For Red Hat JBoss Fuse 6.3.0, use: 

    JBossFuse:karaf@root> features:addurl mvn:org.drools/drools-karaf-features/VERSION/xml/features-fuse-6_3

    To see the current drools-karaf-features version, see the Supported Component Versions chapter of the Red Hat JBoss BPM Suite Installation Guide.

  4. You can now install the features provided for SwitchYard and Apache Camel integration by running, for example, the following console command: 

    JBossFuse:karaf@root> features:install fuse-bxms-switchyard-rules
JBossFuse:karaf@root> features:install kie-camel
JBossFuse:karaf@root> features:install jbpm-workitems-camel

12.5. Configuring Dependencies

When you configure KIE, Red Hat JBoss BRMS, or Red Hat Jboss BPM Suite in your application, you can follow one of the following approaches to build your OSGi application bundles:

  • Bundle required dependencies into your application bundle. In this approach, you declare all required artifacts as runtime dependencies in your pom.xml. Hence, you need not import the packages that provide these artifacts that you have already added as dependencies.
  • Import the required dependencies into the application bundle. This is a preferred approach for building OSGi bundles as it adheres to the principles of OSGi framework. In this approach, you declare only the API JARs (such as org.kie:kie-api) as dependencies in your application bundle. You will need to install the required Red Hat JBoss BRMS and Red Hat JBoss BPM Suite bundles and then import them in your application.
Warning

The MVELUserGroupCallback class fails to initialize in an OSGi environment. Do not use or include MVELUserGroupCallback as it is not designed for production purposes.

12.6. Installing Red Hat JBoss Fuse Integration Quick Start Applications

The following features for Red Hat JBoss Fuse integration quick start applications are provided by org/jboss/integration/fuse/quickstarts/karaf-features/VERSION/karaf-features-VERSION-features.xml:

  • fuse-bxms-quickstart-switchyard-bpm-service
  • fuse-bxms-quickstart-switchyard-rules-camel-cbr
  • fuse-bxms-quickstart-switchyard-rules-interview
  • fuse-bxms-quickstart-switchyard-rules-interview-container
  • fuse-bxms-quickstart-switchyard-rules-interview-dtable
  • fuse-bxms-quickstart-switchyard-library
  • fuse-bxms-quickstart-switchyard-helpdesk
  • fuse-bxms-quickstart-camel-blueprint-drools-decision-table
  • fuse-bxms-quickstart-camel-spring-drools-decision-table
  • fuse-bxms-quickstart-camel-jbpm-workitems

This file (and supporting repositories) is located in http://repository.jboss.org/nexus/content/repositories/public, which is already configured for use on Red Hat JBoss Fuse out of the box in INSTALLATION_DIRECTORY/etc/org.ops4j.pax.url.mvn.cfg.

Procedure: Installing Quick Start Applications

  1. Add a reference to the features file by running the following console command: 

    JBossFuse:karaf@root> features:addurl mvn:org.jboss.integration.fuse.quickstarts/karaf-features/1.0.0.redhat-VERSION/xml/features

  2. You can now install the quick start applications provided by this features file by running, for example, the following console command: 

    JBossFuse:karaf@root> features:install fuse-bxms-quickstart-switchyard-bpm-service

Procedure: Downloading and Installing Quick Start ZIP Files

  1. Download the quick start application ZIP file.
  2. Unpack the contents of the quick starts directory into your existing INSTALLATION_DIRECTORY/quickstarts directory.
  3. Unpack the contents of the system directory into your existing INSTALLATION_DIRECTORY/system directory.

12.6.1. Testing Your First Quick Start Application

Procedure: Testing Quick Start Application

  1. Start Red Hat JBoss Fuse: 

    $ ./INSTALLATION_DIRECTORY/bin/fuse

  2. Install and start the switchyard-bpm-service by running the following console command: 

    JBossFuse:karaf@root> features:install fuse-bxms-quickstart-switchyard-bpm-service
    Note

    Any dependent features specified by the application’s features file will be installed automatically.

  3. Submit a web service request to invoke the SOAP gateway.

    1. Open a terminal window and navigate to the associated quick start directory that was unpacked from the quick start application ZIP file (in this case, switchyard-bpm-service).

    2. Run the following command: 

      $ mvn clean install
      Note

      You will need the following repositories configured in your settings.xml file:

    3. Run the following command: 

      $ mvn exec:java -Pkaraf

  4. You will receive the following response: 

    SOAP Reply:
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <SOAP-ENV:Header xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"/>
  <soap:Body>
    <ns2:submitOrderResponse xmlns:ns2="urn:switchyard-quickstart:bpm-service:1.0">
      <orderId>test1</orderId>
      <accepted>true</accepted>
      <status>Thanks for your order, it has been shipped!</status>
    </ns2:submitOrderResponse>
  </soap:Body>
</soap:Envelope>