JBoss.orgCommunity Documentation

Services Guide

Your guide to services available in JBossESB



This book contains details of the services available within the JBossESB.

1. The Registry
1.1. What is the Registry?
1.1.1. Introduction
1.1.2. Why do I need it?
1.1.3. How do I use it?
1.1.4. Registry Vs Repository
1.1.5. SOA components
1.1.6. UDDI
1.1.7. The Registry and JBossESB
1.2. Configuring the Registry
1.2.1. The Components Involved
1.2.2. The Registry Implementation Class
1.2.3. Using JAXR
1.2.4. Using jUDDI Transports
1.2.5. Using Scout and jUDDI
1.2.6. Registry Interceptors
1.3. Registry Configuration Examples
1.3.1. Embedding
1.3.2. RMI using the jbossesb.sar
1.3.3. RMI using your own JNDI Registration of the RMI Service
1.3.4. SOAP
1.4. Registry Troubleshooting
1.4.1. Scout and jUDDI pitfalls
1.4.2. More Information
2. Rule Services
2.1. What is a Rule Service?
2.1.1. Introduction
2.2. Rule Services using Drools
2.2.1. Introduction
2.2.2. Rule Set Creation
2.2.3. Rule Service Consumers
2.2.4. Configuration
2.2.5. Object Paths
2.2.6. Channels
2.2.7. Deploying and Packaging
3. Content-Based Routing
3.1. What is Content-Based Routing?
3.1.1. Introduction
3.1.2. Simple example
3.2. Content-Based Routing using XPath
3.2.1. Introduction
3.2.2. Inline Rule Definitions
3.2.3. External Rule Definitions
3.2.4. Namespaces
3.3. Content-Based Routing using Regex
3.3.1. Introduction
3.3.2. Inline Rule Definitions
3.3.3. External Rule Definitions
3.4. Content-Based Routing Using Drools
3.4.1. Introduction
3.4.2. Three Different Routing Action Classes
3.4.3. Rule-Set Creation
3.4.4. XPath Domain Specific Language
3.5. Content-Based Routing Using Smooks
3.5.1. Introduction
4. Message Transformation
4.1. Overview
4.2. Smooks
4.2.1. Samples and Tutorials
4.3. XSL Transformations
5. jBPM Integration
5.1. Introduction
5.2. Integration Configuration
5.3. jBPM configuration
5.4. Creation and Deployment of a Process Definition
5.5. JBossESB to jBPM
5.5.1. Exception Handling JBossESB to jBPM
5.6. jBPM to JBossESB
5.6.1. EsbNotifier
5.6.2. EsbActionHandler
5.6.3. Exception Handling jBPM -> JBossESB
5.6.4. Scenerio One: Time-out
5.6.5. Scenario Two: Exception Transition
5.6.6. Scenario Three: Exception Decision
6. Service Orchestration
6.1. Introduction
6.2. Orchestrating Web Services
6.3. Orchestration Diagram
6.4. Process Deployment and Instantiation
6.5. Conclusion
7. The Message Store
7.1. Introduction
7.2. Message Store Interface
7.2.1. Transaction
7.3. Configuring the Message Store
8. Security
8.1. Introduction
8.2. Security Service Configuration
8.2.1. Configuring Security on Services
8.3. Authentication
8.3.1. Authentication Request
8.4. JBossESB SecurityContext
8.5. Security Context Propagation
8.6. Customising security
8.7. Provided Login Modules
8.7.1. CertificateLoginModule
8.7.2. Role Mapping
8.8. Password Encryption
8.8.1. Creating an Encrypted Password File
8.8.2. SecurityService
9. References
A. GNU General Public License
A.1. Preamble
A.2.1. Section 0
A.2.2. Section 1
A.2.3. Section 2
A.2.4. Section 3
A.2.5. Section 4
A.2.6. Section 5
A.2.7. Section 6
A.2.8. Section 7
A.2.9. Section 8
A.2.10. Section 9
A.2.11. Section 10
A.2.12. NO WARRANTY Section 11
A.2.13. Section 12
A.3. How to Apply These Terms to Your New Programs
B. Revision History

As the W3C puts it: An SOA is a specific type of distributed system in which the agents are "services": http://www.w3.org/TR/2003/WD-ws-arch-20030808/#id2617708.

The key components of a Service Oriented Architecture are the messages that are exchanged, agents that act as service requesters and service providers, and shared transport mechanisms that allow the flow of messages. A description of a service that exists within an SOA is essentially just a description of the message exchange patter between itself and its users. Within an SOA there are thus three critical roles: requester, provider, and broker.

Service Provider

allows access to services, creates a description of a service and publishes it to the service broker.

Service Broker

hosts a registry of service descriptions. It is responsible for linking a requestor to a service provider.

Service Requester

is responsible for discovering a service by searching through the service descriptions given by the service broker. A requestor is also responsible for binding to services provided by the service provider.

The JBossESB Registry architecture allows for many ways to configure the ESB to use either a Registry or Repository. By default we use a JAXR implementation (Scout) and a UDDI (jUDDI), in an embedded way.

The following properties can be used to configure the JBossESB Registry. In the jbossesb-properties.xml there is section called 'registry':

<properties name="registry">
  <property name="org.jboss.soa.esb.registry.implementationClass"
  <property name="org.jboss.soa.esb.registry.factoryClass"
  <property name="org.jboss.soa.esb.registry.queryManagerURI"
  <property name="org.jboss.soa.esb.registry.lifeCycleManagerURI"
  <property name="org.jboss.soa.esb.registry.securityManagerURI"
  <property name="org.jboss.soa.esb.registry.user" value="root"/>
  <property name="org.jboss.soa.esb.registry.password"  value="root"/>
  <property name="org.jboss.soa.esb.scout.proxy.uddiVersion" value="3.0"/>
  <property name="org.jboss.soa.esb.scout.proxy.uddiNameSpace" value="urn:uddi-org:api_v3"/>
  <property name="org.jboss.soa.esb.scout.proxy.transportClass"
  <!-- specify the interceptors, in order -->
  <property name="org.jboss.soa.esb.registry.interceptors"
  value="org.jboss.internal.soa.esb.services.registry.InVMRegistryInterceptor, org.jboss.internal.soa.esb.services.registry.CachingRegistryInterceptor"/>
  <!-- The following properties modify the cache interceptor behaviour -->
  <property name="org.jboss.soa.esb.registry.cache.maxSize" value="100"/>
  <property name="org.jboss.soa.esb.registry.cache.validityPeriod" value="600000"/>
  <!-- Organization Category to be used by this deployment. -->
  <property name="org.jboss.soa.esb.registry.orgCategory"         

Table 1.1. Registry Properties


A class that implements the jbossesb Registry interface. We have provided one implementation (JAXRRegistry interface).


The class name of the JAXR ConnectionFactory implementation.


The URI used by JAXR to query


The URI used by JAXR to edit.


The URI used to authenticate.


The user used for edits.


The password to go along with the user.


The UDDI version of the query.


The UDDI namespace.


The name of the class used by scout to do the transport from scout to the UDDI.


The list of interceptors that are applied to the configured registry. The codebase currently provides two interceptors, one for handling InVM registration and a second for applying a cache over the registry.

The default interceptor list consists solely the InVM interceptor.


The maximum number of server entries allowed in the cache. If this value is exceeded then entries will be evicted on a LRU basis. The default value is 100 entries.


The validity period of the caching interceptor. This is specified in milliseconds and defaults to 600000 (ten minutes). If this value is zero (or less) then there is no expiry specified on the cache.


The Organization Category name for the ESB instance. Default is "org.jboss.soa.esb.:category".

Property: org.jboss.soa.esb.scout.proxy.transportClass

When using Scout with a UDDI implementation there is an additional parameter that one can set - the transport class that is used for communication between Scout and the UDDI registry. If you are using Scout to communicate with jUDDI v3, we suggest leaving the transportClass as LocalTransport and using jUDDI's esb.juddi.client.xml to use jUDDI's transports (InVM, RMI, WS).

jUDDI's esb.juddi.client.xml resides in the server/<config>/deploy/jbossesb.sar/META-INF directory and contain the concept of a “node”, which is a jUDDI registry location. Use the node settings to determine whether you want to use JAX-WS, InVM, or RMI as your transport:

        <!-- required 'default' node -->
        <description>Main jUDDI node</description>
    <property name="serverName" value="localhost" />
        <property name="serverPort" value="8880" />
        <!-- JAX-WS Transport
       <!-- In VM Transport Settings 
    <!-- RMI Transport Settings -->

As seen above, a transport should specify a proxyTransport, a URL for all of the supported UDDI API (inquiry, publish, security, subscription, subscription-listener, custodytransfer), and a jUDDI API URL. The RMI transport also includes JNDI settings. By default, the RMI settings are enabled – to switch transports you can comment them out and enable whichever of the transports you choose.

Property: org.jboss.soa.esb.scout.proxy.transportClass

When using Scout with jUDDI there is an additional parameter that one can set. This is the transport class that should be used for communication between Scout and jUDDI. Thus far there are 4 implementations of this class which are based on SOAP, SAAJ, RMI and Local (embedded java). If you are using Scout to communicate with jUDDI v3, we suggest leaving the transportClass as LocalTransport and using jUDDI's uddi.xml to use jUDDI's transports (InVM, RMI, WS).

However, when communicating with another UDDI registry (Systinet, SOA Software, etc), it is preferable to use scout's JAXR transports. There are 4 implementations of this class which are based on SOAP, SAAJ, RMI and Local (embedded java). Note that when you change the transport, you will also have to change the query and lifecycle URIs. For example:

For jUDDI we have two requirements that need to be fulfilled:

  1. access to the jUDDI database. You will need to create a schema in your database, and add the jbossesb publisher. The product/install/jUDDI-registry directory contains db create scripts for you favorite database.

  2. esb.juddi.xml and esb.juddi.client.xml. The configuration of jUDDI itself.


The database can be automatically created if the user you have created has enough rights to create tables. jUDDI should be able to create a database for any database that has a Hibernate dialect associated with it.

As mentioned before, by default the JBossESB is configured to use the JAXR API using Scout as its implementation and jUDDI as the registry. Here are some examples of how you can deploy this combo.

All ESB components (with components we really mean JVMs in this case) can embed the registry and they all can connect to the same database (or different once if that makes sense).

Properties example:

<properties name="registry">

        <property name="org.jboss.soa.esb.registry.implementationClass"                     

        <property name="org.jboss.soa.esb.registry.factoryClass"                    

        <property name="org.jboss.soa.esb.registry.queryManagerURI"                 

        <property name="org.jboss.soa.esb.registry.lifeCycleManagerURI" 

        <property name="org.jboss.soa.esb.registry.securityManagerURI" 

        <property name="org.jboss.soa.esb.registry.user" value="jbossesb"/>
        <property name="org.jboss.soa.esb.registry.password" value="password"/>
        <property name="org.jboss.soa.esb.scout.proxy.transportClass"                                                   


Deploy a version of the jUDDI that brings up an RMI service. The JBossESB deploys the RMI service by default – it starts the registry within the jbossesb.sar.

The jbossesb.sar also registers a RMI service.

Properties example:

<properties name="registry">
  <property name="org.jboss.soa.esb.registry.implementationClass"

  <property name="org.jboss.soa.esb.registry.factoryClass"

  <property name="org.jboss.soa.esb.registry.queryManagerURI"

  <property name="org.jboss.soa.esb.registry.lifeCycleManagerURI"
  <property name="org.jboss.soa.esb.registry.securityManagerURI"
  <property name="org.jboss.soa.esb.registry.user" value="jbossesb"/>
  <property name="org.jboss.soa.esb.registry.password" value="password"/>
  <property name="org.jboss.soa.esb.scout.proxy.transportClass"

The juddi.war is configured to bring up a RMI Service, which is triggered by the following setting in the web.xml

<!--  uncomment if you want to enable making calls in juddi with rmi  -->

Make sure to include, for example, the following JNDI settings in your juddi.properties:

# JNDI settings (used by RMITransport)



The RMI clients need to have the scout-client.jar in their classpath.

If you don't want to deploy the juddi.war you can setup one of the ESB components that runs in the the same JVM as jUDDI to register the RMI service. While the other applications need to be configured to use RMI.

Properties example: For application 1 you need the Local settings:

<properties name="registry">
    <property name="org.jboss.soa.esb.registry.implementationClass" 

    <property name="org.jboss.soa.esb.registry.factoryClass"

        <property name="org.jboss.soa.esb.registry.queryManagerURI"

        <property name="org.jboss.soa.esb.registry.lifeCycleManagerURI"

        <property name="org.jboss.soa.esb.registry.securityManagerURI"

        <property name="org.jboss.soa.esb.registry.user" value="jbossesb"/>
        <property name="org.jboss.soa.esb.registry.password" value="password"/>
        <property name="org.jboss.soa.esb.scout.proxy.transportClass" 

while for application2 you need the RMI settings:

<properties name="registry">
    <property name="org.jboss.soa.esb.registry.implementationClass"

    <property name="org.jboss.soa.esb.registry.factoryClass"

        <property name="org.jboss.soa.esb.registry.queryManagerURI"

        <property name="org.jboss.soa.esb.registry.lifeCycleManagerURI"
        <property name="org.jboss.soa.esb.registry.user" value="jbossesb"/>
        <property name="org.jboss.soa.esb.registry.password" value="password"/>
        <property name="org.jboss.soa.esb.scout.proxy.transportClass"

Where the hostname of the queryManagerURI and lifeCycleManagerURI need to point to the hostname on which jUDDI is running (which would be where application1 is running). Obviously application1 needs to have access to a naming service. To do the registration process you need to do something like:

//Getting the JNDI setting from the config

Properties env = new Properties();
env.setProperty(RegistryEngine.PROPNAME_JAVA_NAMING_PROVIDER_URL, providerURL);
InitialContext context = new InitialContext(env);
Inquiry inquiry = new InquiryService();
log.info("Setting " + INQUIRY_SERVICE + ", " + inquiry.getClass().getName());
mInquery = inquiry;
context.bind(INQUIRY_SERVICE, inquiry);
Publish publish = new PublishService();
log.info("Setting " + PUBLISH_SERVICE + ", " + publish.getClass().getName());
mPublish = publish;
context.bind(PUBLISH_SERVICE, publish);

The JBossESB Rule Service allows you to deploy rules created in Drools as services on the ESB. This is beneficial, because it means you don't have to develop as much client code to integrate rules into your application environment, and rules can be accessed as part of an action chain or orchestrated business process. To understand these types of services, you should first learn about Drools.

Rule Services are supported by the BusinessRulesProcessor action class and the DroolsRuleService, which implement the RuleService interface. While it is possible to use rule engines other than Drools, only Drools is supported out the the box. The BusinessRulesProcessor supports rules loaded from the classpath that are defined in .drl files, .dsl files (domain specific language support), and .xls (decision table support) files. These are primarily for testing, prototypes, and very simple rule services. There is no way to specify multiple rule files in the jboss-esb.xml file, so complex rule services need to use the Drools KnowledgeAgent.

The RuleService uses the KnowledgeAgent to access rule packages from the Drools BRMS or local file system. These rule packages can contain thousands of rules, the source of which can be:

The BusinessRulesProcessor action supports both Drools stateless and stateful execution models. Most rule services will be stateless. That is, a message will be sent to the rule service that includes all the facts to be inserted into the rule engine in the message body, the rules will execute, updating either the message and / or the facts. Stateful execution takes place over time, with several messages being sent to the rule service, the rules being executed each time, the message and / or facts being updated each time, and a final message that tells the rule service to dispose of the stateful session working memory of the rule engine. There are limitations in this configuration, namely that there can only be a single (stateful) rule service in the message flow. This may change in the future, when there are better ways to identify a stateful conversation over the ESB.

A rule set can be created using the JBoss Developer Studio which includes a plug-in for Drools, or with Eclispe 3.5 and the plugin installed (see Drools download site for the plugin). Since the message is added as a global, you need to add jbossesb-rosetta.jar to your Drools project.

You can also write your rules using the Drools BRMS Business Rule Editor. When using the Drools BRMS, it is not necessary to add the ESB Message class to the imports, as long as jbossesb-rosetta.jar is somewhere on the classpath of the BRMS web application.

For the most part, rules can be written without regard to their deployment on the ESB as a service. There are a few caveats however:

The consumer of a rule service has little to worry about. In a rule service environment there is no need for the consumer to worry about creating rulebases, creating working memories, inserting facts, or firing the rules. Instead the consumer just has to worry about adding facts to the message, and possibly some properties to the message.

In some cases the client is ESB aware, and will add the objects to the message directly:

MessageFactory factory = MessageFactory.getInstance();

message = factory.getMessage(MessageType.JAVA_SERIALIZED);
order = new Order();
order.setUnitPrice(new Float("20.0"));
message.getBody().add("Order", order);

In other cases the data may be in an XML message, and a transformation service will be added to the message flow to transform the XML to POJOs before the rule service is invoked.

Using stateful rule execution requires a few properties to be added the messages. For the first message,

message.getProperties().setProperty("dispose", false);

message.getProperties().setProperty("continue", false);

For all the subsequest messages but the final message,

message.getProperties().setProperty("dispose", false);

message.getProperties().setProperty("continue", true);

For the final message:

message.getProperties().setProperty("dispose", true); 

message.getProperties().setProperty("continue", true);

These can be added directly by an ESB aware client. A non-ESB aware client would have to communicate the position of the message (first, ongoing, last) in the data, and an action class would need to be added to the pipeline to add the properties to the ESB message (see quickstarts/business_ruleservice_stateful for an example of this type of service).

Configuration of a rule service is in the jboss-esb action element for the service. Several configuration parameters are required or optional

The action class and name is required:

<action class="org.jboss.soa.esb.actions.BusinessRulesProcessor"

This configures the action class and its name. The name is user defined.

One of the following is also required:

<property name="ruleSet" value="drl/OrderDiscount.drl" />

for specifying a drl file, or

<property name="ruleSet" value="dsl/approval.dslr" />
<property name="ruleLanguage" value="dsl/acme.dsl" />

for specifying a dsl and dslr (domain specific language) files , or

<property name="decisionTable" value="PolicyPricing.xls" />

or specifying a decisionTable on the classpath, or

<property name="ruleAgentProperties"
           value="brmsdeployedrules.properties" />

for specifying a properties file on the classpath that tells the rule agent how to find the rule package. This could specify a url or a local file system.

Several example configurations follow.

  1. Rules are in a drl, execution is stateless:

    <action class="org.jboss.soa.esb.actions.BusinessRulesProcessor"
        <property name="ruleSet" value="drl/OrderDiscount.drl" />
        <property name="ruleReload" value="true" />
        <property name="object-paths">
            <object-path esb="body.Order" />
  2. Rules are in a drl, execution is stateful.

    In this scenario, a service may receive multiple messages over time and wish to use rules to accumulate data across this message set. Each time a message is received, the rules will be fired within the context of a single Stateful Session. The active Session can be disposed of (reset) via the “dispose” property.

    <action class="org.jboss.soa.esb.actions.BusinessRulesProcessor"
        <property name="ruleSet"
                  value="drl/OrderDiscountOnMultipleOrders.drl" />
        <property name="ruleReload" value="false" />
        <property name="stateful" value="true" >
        <property name="object-paths">
            <object-path esb="body.Customer" />
            <object-path esb="body.Order" />
  3. Rules are in a drl, execution is stateful, audit logging is enabled, and the Drools clockType, eventProcessingType and channels are set to aid in Complex Event Processing (CEP).

    In this scenario, a service may want to perform Drools audit logging so that the Drools Eclipse editor can parse the audit file for debugging. It also wants to specify a specific clock type or event processing type for CEP. Last it wants to specify Drools “Channels” to send Objects to (“Channels” used to be known as “ExitPoints”).

    <action class="org.jboss.soa.esb.actions.BusinessRulesProcessor"
        <property name="ruleSet" value="drl/OrderEvents.drl" />
        <property name="ruleReload" value="false" />
        <property name="stateful" value="true" >
        <property name="ruleFireMethod" value="FIRE_UNTIL_HALT" />
        <property name="ruleAuditType" value="THREADED_FILE" />
        <property name="ruleAuditFile" value="myaudit" />
        <property name="ruleAuditInterval" value="1000" />
        <property name="ruleClockType" value="REALTIME" />
        <property name="ruleEventProcessingType" value="STREAM" />
        <property name="object-paths">
            <object-path esb="body.OrderStatus"
                entry-point="OrderStatusStream" />
            <object-path esb="body.OrderInfo"
                entry-point="OrderInfoStream" />
        <property name="channels">
            <!-- chan1 and chan2 are equivalent
                (but timeout only applies if async is false) -->
            <send-to channel-name="chan1"
                service-category="cat1" service-name="svc1" />
            <send-to channel-name="chan2"
                service-category="cat1" service-name="svc1"
                async="true" timeout="30000"
                set-payload-location="org.jboss.soa.esb.message.defaultEntry" />
            <!-- chan3 is a custom channel -->
            <send-to channel-name="chan3"
                channel-class="com.example.MyChannel" />
  4. Rules are in a Domain Specific Language, execution is stateless:

    <action class="org.jboss.soa.esb.actions.BusinessRulesProcessor"
        <property name="ruleSet" value="dsl/approval.dslr" />
        <property name="ruleLanguage" value="dsl/acme.dsl" />
        <property name="ruleReload" value="true" />
        <property name="object-paths">
            <object-path esb="body.Driver" />
            <object-path esb="body.Policy" />
  5. Rules are in a DecisionTable, execution is stateless:

    <action class="org.jboss.soa.esb.actions.BusinessRulesProcessor"
        <property name="decisionTable"
                  value="decisionTable/PolicyPricing.xls" />
        <property name="ruleReload" value="true" />
        <property name="object-paths">
            <object-path esb="body.Driver" />
            <object-path esb="body.Policy" />
  6. Rules are in the BRMS, execution is stateless.

    <action class="org.jboss.soa.esb.actions.BusinessRulesProcessor"
        <property name="ruleAgentProperties"
                  value="ruleAgent/brmsdeployedrules.properties" />
        <property name="object-paths">
            <object-path esb="body.Driver" />
            <object-path esb="body.Policy" />

The action attributes to the action tag are show in Table 1. The attributes specify which action is to be used and which name this action is to be given.

The action properties are shown in Table 2. The properties specify the set of rules (ruleSet) to be used in this action.




Finally, the Object Mapper can flatten out entire collections. For example a collectoin Orders will be unrolled, and each order object inserted into working memory.

To send an Object to a Drools Channel in DRL, the syntax is very simple and goes on the RHS (Right Hand Side) of the rule definition:


For this DRL to be functional, the "mychannel" channel needs to be registered to do this you add a "channels" property section to the jboss-esb.xml configuration. You can define as many Channels as you want, for the same or for different Channel names. (For a particular Channel name, the Channels will be executed in the same order as they appear in the configuration.) The types of Channels supported are:

Typically, information within the ESB is conveniently packaged, transferred, and stored in the form of a message. Messages are addressed to Endpoint References (services or clients), that identify the machine/process/object that will ultimately deal with the content of the message. However, what happens if the specified address is no longer valid? For example, the service has failed or been removed from service? It is also possible that the service no longer deals with messages of that particular type; in which case, presumably some other service still handles the original function, but how should the message be handled? What if other services besides the intended recipient are interested in the message's content? What if no destination is specified?

One possible solution to these problems is Content-Based Routing. Content-based routing seeks to route messages, not by a specified destination, but by the actual content of the message itself. In a typical application, a message is routed by opening it up and applying a set of rules to its content to determine the parties interested in its content.

The ESB can determine the destination of a given message based on the content of that message, freeing the sending application from having to know anything about where a message is going to end up.

Content-based routing and filtering networks are extremely flexible and very powerful. When built upon established technologies such as MOM (Message Oriented Middleware), JMS (Java Message Services), and XML (Extensible Markup Language) they are also reasonably easy to implement.

JBossESB ships with three slightly different routing action classes. Each of these action classes implements an Enterprise Integration Pattern. For more information of the Enterprise Integration Pattern you can check the JBossESB Wiki. The following actions are supported:

For XML-based messages it is convenient to do XPath based evaluation. To support this we ship a “Domain Specific Language” implementation which allows us to use XPath expressions in the rule file. defined in the XPathLanguage.dsl. To use it you need to reference it in your ruleSet with:

expander XPathLanguage.dsl

Currently the XPath Language makes sure the message is of the type JBOSS_XML and it defines

Now that we have seen all the individual pieces how does it all tie together? It basically all comes down to configuration at this point, which is all done in your jboss-esb.xml. The image shows a service configuration fragment. In this fragment the service is listening on a JMS queue.

Each EsbMessage is passed on to in this case the ContentBasedRouter action class which is loaded with a certain rule set. It sets the EsbMessage into Working Memory, fires the rules, obtains the list of destinations and routes copies of the EsbMessage to these services. It uses the rule set JbossESBRules.drl, which matches two destinations, name 'xml-destination' and 'serialized-destination'. These names are mapped to real service names in the 'route-to' section.

            description="CBR Service">
                  <jms-listener name="CBR-Listener"                  
                            busidref="QueueA" maxThreads="1">             
             <action class="org.jboss.soa.esb.actions.ContentBasedRouter" 
                        <property name="ruleSet" value="JBossESBRules.drl"/>
                        <property name="ruleReload" value="true"/>
                        <property name="destinations">
                           <route-to destination-name="xml-destination" 
                       service-name="jbossesbtest1" /> 
                           <route-to destination-name="serialized-destination"
                    service-name="jbossesbtest2" /> 
                        <property name="object-paths">
                <object-path esb="body.test1" /> 
                <object-path esb="body.test2" /> 

The action attributes to the action tag are show in the table below. The attributes specify which action is to be used and which name this action is to be given.

The action properties are shown in the next table. The properties specify the set of rules (ruleSet) to be used in this action.

Table 3.2. Action Configuration Properties

ruleSet Name of the filename containing the Drools ruleSet. The set of rules that is used to evaluate the content. Only 1 ruleSet can be given for each CBR instance.
ruleLanguage Optional reference to a file containing the definition of a Domain Specific Language to be used for evaluating the rule set.
ruleAgentProperties This property points to a rule agent properties file located on the classpath. The properties file can contain a property that points to precompiled rules packages on the file system, in a directory, or identified by an URL for integration with the BRMS. See the “KnowledgeAgent” section below for more information.
ruleReload Optional property which can be to true to enable 'hot' redeployment of rule sets. Note that this feature will cause some overhead on the rules processing. Note that rules will also reload if the .esb archive in which they live is redeployed.
stateful Optional property which tells the RuleService to use a stateful session where facts will be remembered between invokations. See the “Stateful Rules” section for more information about stateful rules.
destinations A set of route-to properties each containing the logical name of the destination along with the Service category and name as referenced in the registry. The logical name is the name which should be used in the rule set.
object-paths Optional property to pass Message objects into Drools WorkingMemory.
ruleAuditTypeOptional property to have Drools perform audit logging. The log can be read into the Drools Eclipse plugin and inspected. Valid values are CONSOLE, FILE and THREADED_FILE. The default is that no audit logging will be performed.
ruleAuditFileOptional property to define the filepath for audit logging. Only applies to FILE or THREADED_FILE ruleAuditType. The default is "event". Note that JBoss Drools will append ".log" for you. The default location for this file is "." - the current working directory (which for JBoss is in its bin/ directory).
ruleAuditIntervalOptional property to define how often to flush audit events to the audit log. Only applies to the THREADED_FILE ruleAuditType. The default is 1000 (milliseconds).

It is recommended that you package up your code into units of functionality, using .esb packages. The idea is to package up your routing rules alongside the rule services that use the rule sets. The example below shows a layout of the simple_cbr quickstart to demonstrate a typical package.

|   jbm-queue-service.xml
|   SimpleCBRRules-XPath.drl
|   SimpleCBRRules.drl
|       deployment.xml
|       jboss-esb.xml
                            |   MyJMSListenerAction.class
                            |   ReturnJMSMessage.class
                            |   RouteExpressShipping.class
                            |   RouteNormalShipping.class

Finally make sure to deploy and reference the jbrules.esb in your deployment.xml.


The SmooksAction can be used for splitting HUGE messages into split fragments and performing Content-Based Routing on these split fragments.

An example of this might be a huge order message with thousands/millions of order items per message. You might need to split the order up by order item and route each order item split fragment to one or more destinations based on the fragment content. This example can be illustrated as follows:

The above illustration shows how we would like to perform the by-order-item splitting operation and route the split messages to file. The split messages contain a full XML document with data merged from the order header and the order item in question i.e. not just a dumb split. In this illustration, we simply route all the message fragments to file, but with the Smooks Action, we can also route the fragment messages to JMS and to a Database and in different formats (EDI, populated Java Objects, etc).

The Smooks configuration for the above example would look as follows.

(1) <jb:bindings beanId="order" class="java.util.HashMap" createOnElement="order">
        <jb:value property="orderId" decoder="Integer" data="order/@id"/>
        <jb:value property="customerNumber" decoder="Long" data="header/customer/@number"/>
        <jb:value property="customerName" data="header/customer"/>
        <jb:wiring property="orderItem" beanIdRef="orderItem"/>
(2) <jb:bindings beanId="orderItem" class="java.util.HashMap" createOnElement="order-item">
        <jb:value property="itemId" decoder="Integer" data="order-item/@id"/>
        <jb:value property="productId" decoder="Long" data="order-item/product"/>
        <jb:value property="quantity" decoder="Integer" data="order-item/quantity"/>
        <jb:value property="price" decoder="Double" data="order-item/price"/>

(3) <file:outputStream openOnElement="order-item" resourceName="orderItemSplitStream">

        <file:highWaterMark mark="3"/>

(4) <ftl:freemarker applyOnElement="order-item">
            <ftl:outputTo outputStreamResource="orderItemSplitStream"/>

Resource configurations #1 and #2 are there to bind data from the source message into Java Objects in the Smooks bean context. In this case, we're just binding the data into HashMaps. The Map being populated in configuration #2 is recreated and repopulated for every order item as the message is being filtered. The populated Java Objects (from resources #1 and #2) are used to populate a FreeMarker template (resource #4), which gets applied on every order item, with the result of the templating operation being output to a File OutputStream (resource #3). The File OutputStream (resource #3) also gets applied on every order item, managing the file output for the split messages.

What the above does not show is how to perform the content based routing using <condition> elements on the resources. It also doesn't demonstrate how to route fragments to to message aware endpoints. We will be adding a quickstart dedicated to demoing these features of the ESB. Check the User Forum for details.

JBossESB 4.8 upgrades to Smooks v1.1, which means that the split described above can be done without having to define the binding configurations (#1 and #2). For more on how to do this, see the documentation on “FreeMarker Transforms using NodeModels” in section 4 of the Smooks User Guide.

[1] Note that some of the ESB Quickstarts are still using the older “SmooksTransformer” action class. The SmooksAction is a more flexible and easier to use alternative to the SmooksTransformer. The SmooksTransformer will be deprecated in a future release (and removed later again).

The jbpm.esb deployment that ships with the ESB includes the full jBPM runtime and the jBPM console. The runtime and the console share a common jBPM database. The ESB DatabaseInitializer mbean creates this database on startup. The configuration for this mbean is found in the file jbpm.esb/jbpm-service.xml.

<classpath codebase="deploy" archives="jbpm.esb"/>
<classpath codebase="deploy/jbossesb.sar/lib" 

<mbean code="org.jboss.internal.soa.esb.dependencies.DatabaseInitializer"
   <attribute name="Datasource">java:/JbpmDS</attribute>
   <attribute name="ExistsSql">select * from JBPM_ID_USER</attribute>
   <attribute name="SqlFiles">

<mbean code="org.jboss.soa.esb.services.jbpm.configuration.JbpmService"

The first Mbean configuration element contains the configuration for the DatabaseInitializer. By default the attributes are configured as follows:

The DatabaseInitializer mbean is configured in jbpm-service.xml to wait for the JbpmDS to be deployed, before deploying itself. The second mbean “JbpmService” ties the lifecycle of the jBPM job executor to the jbpm.esb lifecycle - it starts a job executor instance on startup and stops it on shutdown. The JbpmDS datasource is defined in the jbpm-ds.xml and by default it uses a HSQL database. In production you will want change to a production strength database. All jbpm.esb deployments should share the same database instance so that the various ESB nodes have access to the same processes definitions and instances.

The jBPM console is a web application accessible at http://localhost:8080/jbpm-console, when you start the server. The login screen is shown below.

Please check the jBPM documentation [TB-JBPM-USER] to change the security settings for this application, which will involve change some settings in the conf/login-config.xml. The console can be used for deploying and monitoring jBPM processes, but is can also be used for human task management. For the different users a customized task list will be shown and they can work on these tasks. The quickstart bpm_orchestration4 [JBESB-QS] demonstrates this feature.

The jbpm.esb/META-INF directory contains the deployment.xml and the jboss-esb.xml. The deployment.xml specifies the resources this esb archive depends on:


The jboss-esb.xml file deploys one internal service, called JBpmCallbackService:

  <service category="JBossESB-Internal" name="JBpmCallbackService"
    description="Service which makes Callbacks into jBPM">
      <jms-listener name="JMS-DCQListener" 
        busidref="jBPMCallbackBus" maxThreads="1" />
    <actions mep="OneWay">
      <action name="action" 

This service listens to the jBPMCallbackBus, which by default is a JMS Queue on either a JBossMQ (jbmq-queue-service.xml) or a JBossMessaging (jbm-queue-service.xml) messaging provider. Make sure only one of these files gets deployed in your jbpm.esb archive. If you want to use your own provider simple modify the provider section in the jboss-esb.xml to reference your JMS provider. shown in this example:

  <jms-provider name="CallbackQueue-JMS-Provider" 
    <jms-bus busid="jBPMCallbackBus">
      <jms-message-filter dest-type="QUEUE" 
        dest-name="queue/CallbackQueue" />


For more details on what the JbpmCallbackService does, please see the “jBPM to ESB” section later on in this chapter.

The configuration of jBPM itself is managed by three files, the jbpm.cfg.xml and the hibernate.cfg.xml and the jbpm.mail.templates.xml.

By default the jbpm.cfg.xml is set to use the JTA transacion manager, as defined in the section:

<service name="persistence">
    <bean class="org.jbpm.persistence.jta.JtaDbPersistenceServiceFactory">
      <field name="isTransactionEnabled"><false/></field>
      <field name="isCurrentSessionEnabled"><true/></field>
      <!--field name="sessionFactoryJndiName">
      <string value="java:/myHibSessFactJndiName" />

Other settings are left to the default jBPM settings.

The hibernate.cfg.xml is also slightly modified to use the JTA transaction manager

<!-- JTA transaction properties (begin) ===
    ==== JTA transaction properties (end) -->
<property name="hibernate.transaction.factory_class">

<property name="hibernate.transaction.manager_lookup_class">

Hibernate is not used to create the database schema, instead we use our own DatabaseInitiazer mbean, as mentioned in the previous section.

The jbpm.mail.templates.xml is left empty by default. For each more details on each of these configuration files please see the jBPM documentation.

To create a Process Definition we recommend using the eclipse based jBPM Process Designer Plugin [KA-JBPM-GPD]. You can either download and install it to eclipse yourself, or use JBoss Developer Studio. The image below shows the graphical editor.

The graphical editor allows you to create a process definition visually. Nodes and transitions between nodes can be added, modified or removed. The process definition saves as an XML document which can be stored on a file system and deployed to a jBPM instance (database). Each time you deploy the process instance jBPM will version it and will keep the older copies. This allows processes that are in flight to complete using the process instance they were started on. New process instances will use the latest version of the process definition.

To deploy a process definition the server needs to be up and running. Only then can you go to the 'Deployment' tab in the graphical designer to deploy a process archive (par). Figure 3 shows the “Deployment” tab view.

In some cases it would suffice to deploy just the processdefinition.xml, but in most cases you will be deploying other type of artifacts as well, such as task forms. It is also possible to deploy Java classes in a par, which means that they end up in the database where they will be stored and versioned. However it is strongly discouraged to do this in the ESB environment as you will risk running into class loading issues. Instead we recommend deploying your classes in the lib directory of the server. You can deploy a process definition

  1. straight from the eclipse plugin, by clicking on the “Test Connection..” button and, on success, by clicking on the “Deploy Process Archive” button,

  2. by saving the deployment to a par file and using the jBPM console to deploy the archive, see Figure 4, or finally,

  3. by using the DeployProcessToServer jBPM ant task.

JBossESB can make calls into jBPM using the BpmProcessor action. This action uses the jBPM command API to make calls into jBPM. The following jBPM commands have been implemented:

The configuration for this action in the jboss-esb.xml looks like

<action name="create_new_process_instance" 

  <property name="command" value="StartProcessInstanceCommand" />
  <property name="process-definition-name" value="processDefinition2"/>
  <property name="actor" value="FrankSinatra"/>                                                 
  <property name="esbToBpmVars">
  <!-- esb-name maps to getBody().get("eVar1") -->
    <mapping esb="eVar1" bpm="counter" default="45" />
    <mapping esb="BODY_CONTENT" bpm="theBody" />


There are two required action attributes:

  1. name

    Required attribute. You are free to use any value for the name attribute as long as it is unique in the action pipeline.

  2. class

    Required attribute. This attributes needs to be set to “org.jboss.soa.esb.services.jbpm.actions.BpmProcessor”

Furthermore one can configure the following configuration properties:

Table 5.3. Configuration Properties


Needs to be one of: NewProcessInstanceCommand, StartProcessInstanceCommand, GetProcessInstanceVariablesCommand or CancelProcessInstanceCommand.



required property for the NewProcessInstanceCommand and StartProcessInstanceCommand if the process-definition-id property is not used. The value of this property should reference a process definition that is already deployed to jBPM and of which you want to create a new instance. This property does not apply to the CancelProcessInstanceCommand.



required property for the NewProcessInstanceCommand and StartProcessInstanceCommand if the process-definition-name property is not used. The value of this property should reference a process definition id in jBPM of which you want to create a new instance. This property does not apply to the CancelProcessInstanceCommand.



specifies the jBPM actor id, which applies to the NewProcessInstanceCommand and StartProcessInstanceCommand only.



optional property to specify the value of the jBPM key. For example one can pass a unique invoice id as the value for this key. On the jBPM side this key is as the “business” key id field. The key is a string based business key property on the process instance. The combination of business key + process definition must be unique if a business key is supplied. The key value can hold an MVEL expression to extract the desired value from the EsbMessage. For example if you have a named parameter called “businessKey” in the body of your message you would use “body.businessKey”. Note that this property is used for the NewProcessInstanceCommand and StartProcessInstanceCommand only.



This property only applies to the StartProcessInstanceCommand, and is of use only if there are more then one transition out of the current node. If this property is not specified the default transition out of the node is taken. The default transition is the first transition in the list of transition defined for that node in the jBPM processdefinition.xml.



optional property for the NewProcessInstanceCommand and StartProcessInstanceCommand. This property defines a list of variables that need to be extracted from the EsbMessage and set into jBPM context for the particular process instance. The list consists of mapping elements. Each mapping element can have the following attributes:

  • esb

    required attribute which can contain an MVEL expression to extract a value anywhere from the EsbMessage.

  • bpm

    optional attribute containing the name which be used on the jBPM side. If omitted the esb name is used.

  • default

    optional attribute which can hold a default value if the esb MVEL expression does not find a value set in the EsbMessage.

  • bpmToEsbVars

    structurally identical to the “esbToBpmVars” property (above). Used with the GetProcessInstanceVariablesCommand for mapping jBPM process instance variables (root token variables) onto the ESB message.

  • reply-to-originator

    Optional property for the NewProcessInstanceCommand and StartProcessInstanceCommand. If this property is specified, with a value of true, then the creation of the process instance will store the ReplyTo/FaultTo EPRs of the invoking message within the process instance. These values can then be used within subsequent EsbNotifier/EsbActionHandler invocations to deliver a message to the ReplyTo/FaultTo addresses.


Finally some variables can be set on the body of the EsbMessage:

The JBossESB to jBPM maybe interesting but the other way around is probably far more interesting jBPM to JBossESB communication provides us with the capability to use jBPM for service orchestration. Service Orchestration itself will be discussed in more detail in the next chapter and here we're focusing on the details of the integration first. The integration implements two jBPM action handler classes. The classes are “EsbActionHandler” and “EsbNotifier”. The EsbActionHandler is a request-reply type action, which drops a message on a Service and then waits for a response while the EsbNotifier only drops a message on a Service and continues its processing. The interaction with JBossESB is asynchronous in nature and does not block the process instance while the Service executes. First we'll discuss the EsbNotifier as it implements a subset of the configuration of EsbActionHandler class.

The EsbNotifier action should be attached to an outgoing transition. This way the jBPM processing can move along while the request to the ESB service is processed in the background. In the jBPM processdefinition.xml we would need attach the EsbNotifier to the outgoing transition. For example the configuration for a “Ship It” node could look like:

<node name="ShipIt">
  <transition name="ProcessingComplete" to="end">
    <action name="ShipItAction" 
        <mapping bpm="entireCustomerAsObject" esb="customer" />
        <mapping bpm="entireOrderAsObject" esb="orderHeader" />
        <mapping bpm="entireOrderAsXML" esb="entireOrderAsXML" />

The following attributes can be specified:

The following subelements can be specified:

The EsbActionHandler is designed to work as a reply-response type call into JBossESB. The EsbActionHandler should be attached to the node. When this node is entered this action will be called. The EsbActionHandler executes and leaves the node waiting for a transition signal. The signal can come from any other thread of execution, but under normal processing the signal will be sent by the JBossESB callback Service. An example configuration for the EsbActionHandler could look like:

<action name="create_new_process_instance" 

  <property name="command" value="StartProcessInstanceCommand" />
  <property name="process-definition-name" value="processDefinition2"/>
  <property name="actor" value="FrankSinatra"/>                                                 
  <property name="esbToBpmVars">
  <!-- esb-name maps to getBody().get("eVar1") -->
    <mapping esb="eVar1" bpm="counter" default="45" />
    <mapping esb="BODY_CONTENT" bpm="theBody" />


The configuration for the EsbActionHandler action extends the EsbNotifier configuration. The extensions are the following subelements:

Optionally you may want to specify a timeout value for this action. For this you can use a jBPM native Timer on the node. If for example you only want to wait 10 seconds for the Service to complete you could add

<timer name='timeout' duedate='10 seconds' transition='time-out'/>

to the node element. Now if no signal is received within 10 seconds of entering this node, the transition called “time-out” is taken.

There are two types of scenarios where exceptions can arise.

  1. The first type of exception is a MessageDeliveryException which is thrown by the ServiceInvoker. If this occurs it means that delivery of the message to the ESB failed. If this happens things are pretty bad and you have probably misspelled the name of the Service you are trying to reach. This type of exception can be thrown from both the EsbNotifier as well as the EsbActionHandler. In the jBPM node one can add an http://docs.jboss.com/jbpm/v3/userguide/processmodelling.html [TB-JBPM-USER] to handle this exception.

  2. The second type of exception is when the Service received the request, but something goes wrong during processing. Only if the call was made from the EsbActionHandler does it makes sense to report back the exception to jBPM. If the call was made from the EsbNotifier jBPM processing has already moved on, and it is of little value to notify the process instance of the exception. This is why the exception-transition can only be specified for EsbAction-Handler.

To illustrate the type of error handling that is now possible using standard jBPM features we will discuss some scenarios illustrated below:

When using the EsbActionHandler action and the node is waiting for a callback, it maybe that you want to limit how long you want to wait for. For this scenario you can add a timer to the node. This is how Service1 is setup in Figure 5. The timer can be set to a certain due date. In this case it is set to 10 seconds. The process definition configuration would look like

<node name="Service1">

  <action class=
  <timer name='timeout' duedate='10 seconds' 
  <transition name="ok" to="Service2"></transition>
  <transition name="time-out-transition" to="ExceptionHandling"/>


Node “Service1” has 2 outgoing transitions. The first one is called “ok” while the second one is called “time-out-transition”. Under normal processing the call back would signal the default transition, which is the “ok” transition since it is defined first. However if the execution of the service takes more then 10 seconds the timer will fire. The transition attribute of the timer is set to “time-out-transition”,so this transition will be taken on time-out. In Figure 5 this means that the processing ends up in the “ExceptionHandling” node in which one can perform compensating work.

Scenario 3 is illustrated in the configuration of Service3 and the “exceptionDecision” node that follows it. The idea is that processing of Service3 completes normally and the default transition out of node Service3 is taken. However, somewhere during the Service execution an errorCode was set, and the “exceptionDecision” node checks if a variable called “errorCode” was set. The configuration would look like

<node name="Service3">
  <action class=
        <mapping esb="SomeExceptionCode" bpm="errorCode"/>
  <transition name="ok" to="exceptionDecision"></transition>
<decision name="exceptionDecision">
   <transition name="ok" to="end"></transition>
   <transition name="exceptionCondition" to="ExceptionHandling">
      <condition>#{ errorCode!=void }</condition>

where the esbToBpmVars mapping element extracts the errorCode called “Some-ExceptionCode” from the EsbMessage body and sets in the jBPM context, if this “SomeExceptionCode” is set that is. In the next node “exceptionDecision” the “ok” transition is taken under normal processing, but if a variable called “errorCode” is found in the jBPM context, the “exceptionCondition” transition is taken. This is using the decision node feature of jBPM where transition can nest a condition. Here we check for the existence of the “errorCode” variable using the condition

<condition>#{ errorCode!=void }</condition>

JBossESB provides WS-BPEL support via its Web Service components. For details on these components and how to configure and use them, see the Message Action Guide.


JBoss and JBossESB also have a special support agreement with ActiveEndpoints (http://www.active-endpoints.com/) for their award wining ActiveBPEL WS-BPEL Engine. In support of this, JBossESB ships with a Quickstart dedicated to demonstrating how JBossESB and ActiveBPEL can collaborate effectively to provide a WS-BPEL based orchestration layer on top of a set of Services that don't expose Webservice Interfaces (the “webservice_bpel” Quickstart). JBossESB provides the Webservice Integration and ActiveBPEL provides the Process Orchestration. A number of flash based walk-thrus of this Quickstart are also available online: http://labs.jboss.com/jbossesb/resources/tutorials/bpel-demos/bpel-demos.html.


ActiveEndpoints WS-BPEL engine does not run on versions of JBossAS since 4.0.5. However, it can be deployed and run successfully on Tomcat as our examples illustrate.

A key component of Service Orchestration is to use a flow-chart like design tool to design and deploy processes. The jBPM IDE can be used for just this. Figure 6 shows an example of such a flow-chart, which represents a simplified order process. This example is taken from the bpm_orchestration4 quick start [JBESB-QS] which ships with JBossESB.

In the “Order Process” Diagram three of the nodes are JBossESB Services, the “Intake Order”, “Calculate Discount” and the “Ship It” nodes. For these nodes the regular “Node” type was used, which is why these are labeled with “<<Node>>”. Each of these nodes have the EsbActionHandler attached to the node itself. This means that the jBPM node will send a request to the Service and then it will remain in a wait state, waiting for the ESB to call back into the node with the response of the Service. The response of the service can then be used within jBPM context. For example when the Service of the “Intake Order” responds, the response is then used to populate the “Review Order” form. The “Review Order” node is a “Task Node”. Task Nodes are designed for human interaction. In this case someone is required to review the order before the Order Process can process.

To create the diagram above, select File > New > Other, and from the Selection wizard select “JBoss jBPM “Process Definition” as shown in below. The wizard will direct you to save the process definition. From an organizational point of view it is recommended use one directory per process definition, as you will typically end up with multiple files per process design.

After creating a new process definition. You can drag and drop any item from menu, shown in Figure 8, into the process design view. You can switch between the design and source modes if needed to check the XML elements that are being added, or to add XML fragments that are needed for the integration. Recently a new type of node was added called “ESB Service" [KA-BLOG].

Before building the “Order Process” diagram of Figure 6, we'd need to create and test the three Services. These services are 'ordinary' ESB services and are defined in the jboss-esb.xml. Check the jboss-esb.xml of the bpm_orchestration4 quick start [JBESB-QS] if you want details on them, but they only thing of importance to the Service Orchestration are the Services names and categories as shown in the following jboss-esb.xml fragment:

  <service category="BPM_orchestration4_Starter_Service" 
  description="BPM Orchestration Sample 4: Use this service to start a 
process instance">
            <!-- .... -->                       
  <service category="BPM_Orchestration4" name="IntakeService"
  description="IntakeService: transforms, massages, calculates priority">
            <!-- .... -->
  <service category="BPM_Orchestration4" name="DiscountService"
  <service category="BPM_Orchestration4" name="ShippingService"
            <!-- .... -->

These Service can be referenced using the EsbActionHandler or EsbNotifier Action Handlers as discussed in Chapter 1. The EsbActionHandler is used when jBPM expects a response, while the EsbNotifier can be used if no response back to jBPM is needed.

Now that the ESB services are known we drag the “Start” state node into the design view. A new process instance will start a process at this node. Next we drag in a “Node” (or “ESB Service “if available). Name this Node “Intake Order”. We can connect the Start and the Intake Order Node by selecting “Transition” from the menu and by subsequently clicking on the Start and Intake Order Node. You should now see an arrow connecting these two nodes, pointing to the Intake Order Node.

Next we need to add the Service and Category names to the Intake Node. Select the “Source” view. The “Intake Order Node should look like

<node name="Intake Order">
    <transition name="" to="Review Order"></transition>

and we add the EsbHandlerAction class reference and the subelement configuration for the Service Category and Name, BPM_Orchestration4 and“IntakeService” respectively

<node name="Intake Order">
  <action name="esbAction" class=
    <!-- async call of IntakeService -->
  <transition name="" to="Review Order"></transition>

Next we want to send the some jBPM context variables along with the Service call. In this example we have a variable named “entireOrderAsXML” which we want to set in the default position on the EsbMessage body. For this to happen we add

  <mapping bpm="entireOrderAsXML" esb="BODY_CONTENT" />

which will cause the XML content of the variable “entireOrderAsXML” to end up in the body of the EsbMessage, so the IntakeService will have access to it, and the Service can work on it, by letting it flow through each action in the Action Pipeline. When the last action is reached it the replyTo is checked and the EsbMessage is send to the JBpmCallBack Service, which will make a call back into jBPM signaling the “Intake Order” node to transition to the next node (“Review Order”). This time we will want to send some variables from the EsbMessage to jBPM. Note that you can send entire objects as long both contexts can load the object's class. For the mapping back to jBPM we add an “esbToEsbVars” element. Putting it all together we end up with:

<node name="Intake Order">
<action name="esbAction" class=
<mapping bpm="entireOrderAsXML" esb="BODY_CONTENT" />
<mapping esb="body.entireOrderAsXML" bpm="entireOrderAsXML"/>
<mapping esb="body.orderHeader" bpm="entireOrderAsObject" />
<mapping esb="body.customer" bpm="entireCustomerAsObject" />
<mapping esb="body.order_orderId" bpm="order_orderid" />
<mapping esb="body.order_totalAmount" bpm="order_totalamount" />
<mapping esb="body.order_orderPriority" bpm="order_priority" />
<mapping esb="body.customer_firstName" bpm="customer_firstName" />
<mapping esb="body.customer_lastName" bpm="customer_lastName" />
<mapping esb="body.customer_status" bpm="customer_status" />
<transition name="" to="Review Order"></transition>

So after this Service returns we have the following variables in the jBPM context for this process: entireOrderAsXML, entireOrderAsObject, entireCustomerAsObject, and for demo purposes we also added some flattened variables: order_orderid, order_totalAmount, order_priority, customer_firstName, customer_lastName and customer_status.

In our Order process we require a human to review the order. We therefore add a “Task Node” and add the task “Order Review”, which needs to be performed by someone with actor_id “user”. The XML-fragment looks like

<task-node name="Review Order">
<task name="Order Review">
<assignment actor-id="user"></assignment>
<variable name="customer_firstName"
<variable name="customer_lastName" access="read,write,required">
<variable name="customer_status" access="read"></variable>
<variable name="order_totalamount" access="read"></variable>
<variable name="order_priority" access="read"></variable>
<variable name="order_orderid" access="read"></variable>
<variable name="order_discount" access="read"></variable>
<variable name="entireOrderAsXML" access="read"></variable>
<transition name="" to="Calculate Discount"></transition>

In order to display these variables in a form in the jbpm-console we need to create an xhtml dataform (see the Review_Order.xhtml file in the bpm_orchestration4 quick start [JBESB-QS] and tie this for this TaskNode using the forms.xml file:

<form task="Order Review" form="Review_Order.xhtml"/>
<form task="Discount Review" form="Review_Order.xhtml"/>

Note that in this case the same form is used in two task nodes. The variables are referenced in the Review Order form like

<f:facet name="header">
<h:outputText value="customer_firstName"/>
<h:inputText value="#{var['customer_firstName']}" />

which references the variables set in the jBPM context.

When the process reaches the “Review Node”, as shown in Figure 9. When the 'user' user logs into the jbpm-console the user can click on 'Tasks” to see a list of tasks, as shown in below. The user can 'examine' the task by clicking on it and the user will be presented with a form as shown below. The user can update some of the values and click “Save and Close” to let the process move to the next Node.

The next node is the “Calculate Discount” node. This is an ESB Service node again and the configuration looks like

<node name="Calculate Discount">
<action name="esbAction" class="
<mapping bpm="entireCustomerAsObject" esb="customer" />
<mapping bpm="entireOrderAsObject" esb="orderHeader" />
<mapping bpm="entireOrderAsXML" esb="BODY_CONTENT" />
<mapping esb="order"
bpm="entireOrderAsObject" />
<mapping esb="body.order_orderDiscount" bpm="order_discount" />
<transition name="" to="Review Discount"></transition>

The Service receives the customer and orderHeader objects as well as the entireOrderAsXML, and computes a discount. The response maps the body.order_orderDiscount value onto a jBPM context variable called “order_-discount”, and the process is signaled to move to the “Review Discount” task node.

The user is asked to review the discount, which is set to 8.5. On “Save and Close” the process moves to the “Ship It” node, which again is an ESB Service. If you don't want the Order process to wait for the Ship It Service to be finished you can use the EsbNotifier action handler and attach it to the outgoing transition:

<node name="ShipIt">
<transition name="ProcessingComplete" to="end">
<action name="ShipItAction" class=
<mapping bpm="entireCustomerAsObject" esb="customer" />
 <mapping bpm="entireOrderAsObject" esb="orderHeader" />
 <mapping bpm="entireOrderAsXML" esb="entireOrderAsXML" />

After notifying the ShippingService the Order process moves to the 'end' state and terminates. The ShippingService itself may still be finishing up. In bpm_orchestration4 [JBESB-QS] it uses drools to determine whether this order should be shipped 'normal' or 'express'.

In the previous paragraph we create the process definition and we quietly assumed we had an instance of it to explain the process flow. But now that we have created the processdefinition.xml, we can deploy it to jBPM using the IDE, ant or the jbpm-console (as explained in Chapter 1). In this example we use the IDE and deployed the files: Review_Order.xhtml, forms.xml, gpd.xml, processdefinition.xml and the processimage.jpg. On deployment the IDE creates a par achive and deploys this to the jBPM database. We do not recommend deploying Java code in par archives as it may cause class loading issues. Instead we recommend deploying classes in jar or esb archives.

When the process definition is deployed a new process instance can be created. It is interesting to note that we can use the 'StartProcessInstanceCommand” which allows us to create a process instance with some initial values already set. Take a look at

<service category="BPM_orchestration4_Starter_Service"
description="BPM Orchestration Sample 4: Use this service to start a
 process instance">
<action name="setup_key" class=
<property name="script"
value="/scripts/setup_key.groovy" />
<action name="start_a_new_order_process" class=
<property name="command"
value="StartProcessInstanceCommand" />
<property name="process-definition-name"
value="bpm4_ESBOrderProcess" />
<property name="key" value="body.businessKey" />
<property name="esbToBpmVars">
 <mapping esb="BODY_CONTENT" bpm="entireOrderAsXML" />

where new process instance is invoked and using some groovy script, and the jBPM key is set to the value of 'OrderId' from an incoming order XML, and the same XML is subsequently put in jBPM context using the esbToBpmVars mapping. In the bpm_orchestration4 quickstart [JBESB-QS] the XML came from the Seam DVD Store and the “SampleOrder.xml” looks like

<Order orderId="2" orderDate="Wed Nov 15 13:45:28 EST 2006" statusCode="0"
 netAmount="59.97" totalAmount="64.92" tax="4.95">
<Customer userName="user1" firstName="Rex" lastName="Myers" state="SD"/>
<OrderLine position="1" quantity="1">
<Product productId="364" title="Gandhi"
<OrderLine position="2" quantity="1">
<Product productId="299" title="Lost Horizon" price="29.99"/>


Both ESB as well as jBPM deployments are hot. An extra feature of jBPM is that process deployments are versioned. Newly created process instances will use the latest version while existing process instances will finish using the process deployment on which they where started.

The org.jboss.soa.esb.services.persistence.MessageStore interface is defined as follows:

public interface MessageStore

    public MessageURIGenerator getMessageURIGenerator();
    public URI addMessage (Message message, String classification)
        throws MessageStoreException;
    public Message getMessage (URI uid)
        throws MessageStoreException;
    public void setUndelivered(URI uid)
        throws MessageStoreException;
    public void setDelivered(URI uid)
        throws MessageStoreException;
    public Map<URI, Message> getUndeliveredMessages(String classification)
        throws MessageStoreException;
    public Map<URI, Message> getAllMessages(String classification)
        throws MessageStoreException;
    public Message getMessage (URI uid, String classification)
        throws MessageStoreException;
    public int removeMessage (URI uid, String classification)
        throws MessageStoreException;

The MessageStore is responsible for reading and writing Messages upon request. Each Message must be uniquely identified within the context of the store and each MessageStore implementation uses a URI to accomplish this identification. This URI is used as the “key” for that message in the database.

Messages can be stored within the store based upon classification using addMessage. If the classification is not defined then it is up to the implementation of the MessageStore how it will store the Message. Furthermore, the classification is only a hint: implementations are free to ignore this field if necessary.

The default implementation of the MessageStore is provided by the org.jboss.internal.soa.esb.persistence.format.db.DBMessageStoreImpl class. The methods in this implementation make the required DB connections (using a pooled Database Manager DBConnectionManager).

To override the MessageStore implementation you should look at the MessageActionGuide and the MessagePersister Action.

To configure your Message Store, you can change and override the default service implementation through the following settings found in the jbossesb-properties.xml:

<properties name="dbstore">
  <!--  connection manager type -->
  <property name="org.jboss.soa.esb.persistence.db.conn.manager" value=
    <!-- this property is only used for the j2ee connection manager -->
    <property name="org.jboss.soa.esb.persistence.db.datasource.name"   
    <!-- standalone connection pooling settings -->
    <!--  mysql
    <property name="org.jboss.soa.esb.persistence.db.connection.url"    
    <property name="org.jboss.soa.esb.persistence.db.jdbc.driver"       
    <property name="org.jboss.soa.esb.persistence.db.user"              
      value="kstam"/> -->
    <!--  postgres 
    <property name="org.jboss.soa.esb.persistence.db.connection.url"    
    <property name="org.jboss.soa.esb.persistence.db.jdbc.driver"       
    <property name="org.jboss.soa.esb.persistence.db.user"              
    <property name="org.jboss.soa.esb.persistence.db.pwd"               
      value="postgres"/> -->
    <!-- hsqldb -->
    <property name="org.jboss.soa.esb.persistence.db.connection.url"    
    <property name="org.jboss.soa.esb.persistence.db.jdbc.driver"       
    <property name="org.jboss.soa.esb.persistence.db.user" value="sa"/>
    <property name="org.jboss.soa.esb.persistence.db.pwd" value=""/>    
    <property name="org.jboss.soa.esb.persistence.db.pool.initial.size" 
    <property name="org.jboss.soa.esb.persistence.db.pool.min.size"     
    <property name="org.jboss.soa.esb.persistence.db.pool.max.size"     
    <!--table managed by pool to test for valid connections
        created by pool automatically -->
    <property name="org.jboss.soa.esb.persistence.db.pool.test.table"   
    <property name="org.jboss.soa.esb.persistence.db.pool.timeout.millis"

The section in the property file called “dbstore” has all the settings required by the database implementation of the message store. The standard settings, like URL, db user, password, pool sizes can all be modified here.

The scripts for the required database schema, are again, very simple. They can be found under lib/jbossesb.esb/message-store-sql/<db_type>/create_database.sql of your JBossESB installation. 

The structure of the table can be seen from the sample SQL:

   uuid varchar(128) NOT NULL,
   type varchar(128) NOT NULL,
   message text(4000) NOT NULL,
   delivered varchar(10) NOT NULL,
   classification varchar(10),
   PRIMARY KEY (`uuid`)

The uuid column is used to store a unique key for this message, in the format of a standard URI. A key for a message would look like:

urn:jboss:esb:message:UID: + UUID.randomUUID()_

This logic uses the new UUID random number generator in jdk 1.5. the type will be the type of the stored message. JBossESB ships with JBOSS_XML and JAVA_SERIALIZED currently.

The “message” column will contain the actual message content.

The supplied database message store implementation works by invoking a connection manager to your configured database. Supplied with JBoss ESB is a standalone connection manager, and another for using a JNDI datasource.

To configure the database connection manager, you need to provide the connection manager implementation in the jbossesb-properties.xml. The properties that you would need to change are:

<!--  connection manager type -->
<property name="org.jboss.soa.esb.persistence.db.conn.manager" 
<!--  property name="org.jboss.soa.esb.persistence.db.conn.manager" 
value="org.jboss.soa.esb.persistence.manager.J2eeConnectionManager"/ -->
<!-- this property is only used for the j2ee connection manager -->
<property name="org.jboss.soa.esb.persistence.db.datasource.name" 

The two supplied connection managers for managing the database pool are

The Standalone manager uses C3PO to manage the connection pooling logic, and the J2eeConnectionManager uses a datasource to manage it's connection pool. This is intended for use when deploying your ESB endpoints inside a container such as JBoss AS or Tomcat, etc. You can plug in your own connection pool manager by implementing the interface:

Once you have implemented this interface, you update the properties file with your new class, and the connection manager factory will now use your implementation.

The Security Service is configured along with everything else in jbossesb-properties.xml:

<properties name="security"> 
<property name="org.jboss.soa.esb.services.security.implementationClass"

<property name="org.jboss.soa.esb.services.security.callbackHandler" 
<property name="org.jboss.soa.esb.services.security.sealAlgorithm" 

<property name="org.jboss.soa.esb.services.security.sealKeySize" 

<property name="org.jboss.soa.esb.services.security.contextTimeout" 

<property name= 
<property name="org.jboss.soa.esb.services.security.publicKeystore" 

<property name="org.jboss.soa.esb.services.security.publicKeystorePassword" 

<property name="org.jboss.soa.esb.services.security.publicKeyAlias" 

<property name="org.jboss.soa.esb.services.security.publicKeyPassword" 

<property name="org.jboss.soa.esb.services.security.publicKeyTransformation" 


Table 8.1. jbossesb-properties.xml Security Settings


This is the concrete SecurityService implementation that should be used. Required. Default is JaasSecurityService.



A default CallbackHandler implementation when a JAAS based SecurityService is being used. See “Customizing security” for more information about the callbackHandler property.



The algorithm to use for sealing the SecurityContext.



The size of the secret/symmetric key used to encrypt/decrypt the SecurityContext.



The amount of time in milliseconds that a security context is valid for. This is a global setting that may be overridden on a per service basis by specifying this same property name on the security element in jboss-esb.xml.



Configures a global SecurityContextPropagator. For more details on the SecurityContextPropagator please refer to the “Security Context Propagation”.



Path to the keystore that holds a keys used for encrypting and decrypting data external to the ESB. This is used to encrypt the AuthenticationRequest.



Password to the public keystore.



Alias to use.



Password for the alias if one was specified upon creation.



Cipher transformation in the format: “algorithm/mode/padding”. If not specified this will default to the keys algorithm.


The JAAS login modules are configured in the way you would except using the login-config.xml file located in the conf directory of your JBoss Application Server. So you can use the ones that come pre-configured but also add your own login modules.


By default JBossESB ships with an example keystore which should not be used in production. It is only provided as a sample to help users get security working “out of the box”. The sample keystore can be updated with custom generate key pairs.

Security is configured per-service. A service in JBossESB can be declared as being secured and that it requires authentication. Services are configured by adding a “security” element to the service in jbossesb.xml:

<service category="Security" name="SimpleListenerSecured"> 
   <security moduleName="messaging" runAs="adminRole"
    rolesAllowed="adminRole, normalUsers"
        <property name="property1" value="value1"/> 
        <property name="property2" value="value2"/> 

Example of overriding global configuration settings:

<security moduleName="messaging" 
  runAs="adminRole" rolesAllowed="adminRole">

<property name=
    value="org.xyz.CustomSecurityContextPropagator" /> 


To authenticate a caller, security information needs to be provided. If the call to the service is coming through a gateway, then the gateway will extract the required information from the transport that the gateway works with. For a web service call this would entail extracting either the UsernameToken or the BinarySecurityToken from the security element in the SOAP header.

When a service needs to call another services and that service requires authentication, another authentication process will be performed. So having a chain of services that are all configured for authentication will cause multiple authentications to be performed. To minimize such overhead the ESB will store an encrypted SecurityContext which will be propagated with the ESB Message object between services. If the ESB detects that a Message has a SecurityContext, it checks that the SecurityContext is still valid, and if so, re-authentication is not performed. Note that the SecurityContext is only valid on a single ESB node. If the message is routed to a different ESB node, re-authentication will be required.

This section lists the login modules provided with JBossESB. Please note that all login modules available with JBoss AS are available as well and custom login modules should be easy to add.

This login module performs authentication by verifiying that a certificate passed with the call to the ESB, can be verified against a certificate in a local keystore.

Upon successful authentication the certificates Common Name(CN) will be used to create a principal. If role mapping is in use then it is the CN that will be used in the role mapping. See “Role Mapping” for details on the role mapping functionality.

<security moduleName="CertLogin" rolesAllowed="worker"
  <property name="alias" value="certtest"/>

Example of fragment from login-config.xml

<application-policy name="CertLogin">
flag = "required" >
  <module-option name="keyStoreURL">
  <module-option name="keyStorePassword">storepassword</module-option>
  <module-option name="rolesPropertiesFile">

Configuration files in JBossESB sometimes require passwords which up until now have been specified in clear text in the configuration files. This is a security risk and something that should be avoided. In JBossESB you have the ability to specify a path to a file that contains an encrypted password wherever a password is required.

The licenses for most software are designed to take away your freedom to share and change it. By contrast, the GNU General Public License is intended to guarantee your freedom to share and change free software - to make sure the software is free for all its users. This General Public License applies to most of the Free Software Foundation's software and to any other program whose authors commit to using it. (Some other Free Software Foundation software is covered by the GNU Library General Public License instead.) You can apply it to your programs, too.

When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for this service if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs; and that you know you can do these things.

To protect your rights, we need to make restrictions that forbid anyone to deny you these rights or to ask you to surrender the rights. These restrictions translate to certain responsibilities for you if you distribute copies of the software, or if you modify it.

For example, if you distribute copies of such a program, whether gratis or for a fee, you must give the recipients all the rights that you have. You must make sure that they, too, receive or can get the source code. And you must show them these terms so they know their rights.

We protect your rights with two steps:

Also, for each author's protection and ours, we want to make certain that everyone understands that there is no warranty for this free software. If the software is modified by someone else and passed on, we want its recipients to know that what they have is not the original, so that any problems introduced by others will not reflect on the original authors' reputations.

Finally, any free program is threatened constantly by software patents. We wish to avoid the danger that redistributors of a free program will individually obtain patent licenses, in effect making the program proprietary. To prevent this, we have made it clear that any patent must be licensed for everyone's free use or not licensed at all.

The precise terms and conditions for copying, distribution and modification follow.

You may modify your copy or copies of the Program or any portion of it, thus forming a work based on the Program, and copy and distribute such modifications or work under the terms of Section 1 above, provided that you also meet all of these conditions:

  1. You must cause the modified files to carry prominent notices stating that you changed the files and the date of any change.

  2. You must cause any work that you distribute or publish, that in whole or in part contains or is derived from the Program or any part thereof, to be licensed as a whole at no charge to all third parties under the terms of this License.

  3. If the modified program normally reads commands interactively when run, you must cause it, when started running for such interactive use in the most ordinary way, to print or display an announcement including an appropriate copyright notice and a notice that there is no warranty (or else, saying that you provide a warranty) and that users may redistribute the program under these conditions, and telling the user how to view a copy of this License. (Exception: If the Program itself is interactive but does not normally print such an announcement, your work based on the Program is not required to print an announcement.)

These requirements apply to the modified work as a whole. If identifiable sections of that work are not derived from the Program, and can be reasonably considered independent and separate works in themselves, then this License, and its terms, do not apply to those sections when you distribute them as separate works. But when you distribute the same sections as part of a whole which is a work based on the Program, the distribution of the whole must be on the terms of this License, whose permissions for other licensees extend to the entire whole, and thus to each and every part regardless of who wrote it.

Thus, it is not the intent of this section to claim rights or contest your rights to work written entirely by you; rather, the intent is to exercise the right to control the distribution of derivative or collective works based on the Program.

In addition, mere aggregation of another work not based on the Program with the Program (or with a work based on the Program) on a volume of a storage or distribution medium does not bring the other work under the scope of this License.

You may copy and distribute the Program (or a work based on it, under Section 2 in object code or executable form under the terms of Sections 1 and 2 above provided that you also do one of the following:

  1. Accompany it with the complete corresponding machine-readable source code, which must be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or,

  2. Accompany it with a written offer, valid for at least three years, to give any third party, for a charge no more than your cost of physically performing source distribution, a complete machine-readable copy of the corresponding source code, to be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or,

  3. Accompany it with the information you received as to the offer to distribute corresponding source code. (This alternative is allowed only for noncommercial distribution and only if you received the program in object code or executable form with such an offer, in accord with Subsection b above.)

The source code for a work means the preferred form of the work for making modifications to it. For an executable work, complete source code means all the source code for all modules it contains, plus any associated interface definition files, plus the scripts used to control compilation and installation of the executable. However, as a special exception, the source code distributed need not include anything that is normally distributed (in either source or binary form) with the major components (compiler, kernel, and so on) of the operating system on which the executable runs, unless that component itself accompanies the executable.

If distribution of executable or object code is made by offering access to copy from a designated place, then offering equivalent access to copy the source code from the same place counts as distribution of the source code, even though third parties are not compelled to copy the source along with the object code.

If, as a consequence of a court judgment or allegation of patent infringement or for any other reason (not limited to patent issues), conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot distribute so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not distribute the Program at all. For example, if a patent license would not permit royalty-free redistribution of the Program by all those who receive copies directly or indirectly through you, then the only way you could satisfy both it and this License would be to refrain entirely from distribution of the Program.

If any portion of this section is held invalid or unenforceable under any particular circumstance, the balance of the section is intended to apply and the section as a whole is intended to apply in other circumstances.

It is not the purpose of this section to induce you to infringe any patents or other property right claims or to contest validity of any such claims; this section has the sole purpose of protecting the integrity of the free software distribution system, which is implemented by public license practices. Many people have made generous contributions to the wide range of software distributed through that system in reliance on consistent application of that system; it is up to the author/donor to decide if he or she is willing to distribute software through any other system and a licensee cannot impose that choice.

This section is intended to make thoroughly clear what is believed to be a consequence of the rest of this License.

If you develop a new program, and you want it to be of the greatest possible use to the public, the best way to achieve this is to make it free software which everyone can redistribute and change under these terms.

To do so, attach the following notices to the program. It is safest to attach them to the start of each source file to most effectively convey the exclusion of warranty; and each file should have at least the “copyright” line and a pointer to where the full notice is found.

<one line to give the program's name and a brief idea of what it does.> Copyright (C) <year> <name of author>

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA

Also add information on how to contact you by electronic and paper mail.

If the program is interactive, make it output a short notice like this when it starts in an interactive mode:

Gnomovision version 69, Copyright (C) year name of author Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type “show w”. This is free software, and you are welcome to redistribute it under certain conditions; type “show c” for details.

The hypothetical commands “show w” and “show c” should show the appropriate parts of the General Public License. Of course, the commands you use may be called something other than “show w” and “show c”; they could even be mouse-clicks or menu items--whatever suits your program.

You should also get your employer (if you work as a programmer) or your school, if any, to sign a “copyright disclaimer” for the program, if necessary. Here is a sample; alter the names:

Yoyodyne, Inc., hereby disclaims all copyright interest in the program “Gnomovision” (which makes passes at compilers) written by James Hacker.

<signature of Ty Coon>, 1 April 1989 Ty Coon, President of Vice

This General Public License does not permit incorporating your program into proprietary programs. If your program is a subroutine library, you may consider it more useful to permit linking proprietary applications with the library. If this is what you want to do, use the GNU Library General Public License instead of this License.

Revision History
Revision 1Fri Jul 16 2010David Le Sage, Darrin Mison
Initial conversion from OpenOffice ODT files.