czwartek, 24 kwietnia 2014

jBPM 6 on WebSphere - installation notes...

Brand new tooling for jBPM 6 is out for a while now and it was mainly targeting the open source world so by default it was deployable to JBoss AS 7.x / JBoss EAP 6.x and Tomcat 7. Now it's time to expand more into other containers so let's start with WebSphere (version 8.5.x).

NOTE: This article covers deployment of kie workbench (aka business central). Although this is just one option to make use of jBPM.

So first of all, we need to get WebSphere Application Server 8.5, if you don't have one already you can download the developer edition from here, which is free to be used for development work and not for production.
Once we have binaries downloaded, it's time to install it, I will not cover installation steps here as it's well documented on IBM documentation and there is no special requirements for WebSphere installation. Make sure that after installation you create a server profile, this article covers application server profile.

Tip: when running on Linux you can encounter problem on deployment, actually at upload time that manifest with very weird exception mostly referring to internal classes of WebSphere. To resolve that increase number of open files for example by issuing following command before starting the server:
ulimit -n 300000

Once WebSphere is properly installed and verification script confirm it is up and running we can move on to configuring server instance. Let's start with process definition configuration where we can specify JVM parameters such as heap size and system properties (aka custom properties):

Logon to WebSphere Administrative Console

Java Virtual Machine configuration

Go to Servers > Server Types > WAS app servers
Go to MyServer > Server Infrastructure > Process Definition > Java Virtual Machine

  • Increase heap size 
    • Initial heap size - 1024
    • Max heap size - 2048
NOTE: that heap settings will depend on your environment so please consider these as starting point that might require some adjustments.

Go to Additional properties > Custom properties
  • Set JVM system properties
    • jbpm.ut.jndi.lookup set to jta/usertransaction
    • set to jms/KIE.RESPONSE.ALL 
    • set to false
    • org.apache.sshd.registerBouncyCastle set to true
    • org.uberfire.domain set to WSLogin

This is the mandatory set of system properties to be set but more can be specified, check jbpm documentation for available system properties.

Security configuration

Go to Security > Global security
Ensure the option Enable Application security is checked. 
Go to Users and groups > Manage groups
Create groups: 
  • Application groups :
    • admin, analyst, developer, manager, user
  • Task service groups
    • Accounting, HR, IT, PM

Go to Users and groups > Manage users
Create a single user and add to selected groups above.

Register the SSL certificate from

This is needed in order to enable repository cloning from Github. This is the case of the kie-wb repository examples which are fetched from Github. 

Go to Security > SSL Certificate and Key Management > Manage endpoint security configurations
Go to Outbound section. Go to your server node within the tree. Select the HTTP subnode.
Go to Related Items > Key Stores and certificates
Select the row in the table named NodeDefaultTrustStore
Go to Additional properties > Signer certificates
Click button Retrieve from port
Fill out the form with these values:, Port=443,
Click on Retrieve signer information button, then Ok, and finally, Save to master configuration.

Data source configuration

Create the JDBC provider

Left side panel, click on Resources > JDBC > JDBC Providers
Select the appropriate scope and click on the New button.
Fill out the form. For non-listed database types (i.e: H2, Postgres & Mysql) you need to provide the path to the JDBC driver jar plus the following class name:
  •   H2            org.h2.jdbcx.JdbcDataSource                                 
  •   Postgres   org.postgresql.xa.PGXADataSource                            
  •   Mysql      com.mysql.jdbc.jdbc2.optional.MysqlConnectionPoolDataSource 

When you finish, click Ok. If there are no data entry errors, you should be back at the list of JDBC Providers, where you should now see your new provider displayed.

Create the data source

Left side panel, click on Resources > JDBC > Data sources
Select the appropriate scope and click on the New button.
Fill out the creation form. Set the following JNDI name jdbc/jbpm (must match the data source defined in the persistence.xml file contained in the kie-wb.war)
Select the existing JDBC provider you created. Click Next.
Keep clicking Next until Finish.
Save to master configuration.
Edit the datasource you just created and click on the Custom properties link.
Edit and fill the appropriate values required to set-up the connection. This depends on the database type.
  •    H2            URL, user, password                                  
  •    Postgres   serverName, databaseName, portNumber, user, password 
  •    Mysql      serverName, databaseName, port, user, password       

JMS Configuration

Create Service Integration Bus that will host all the queues required by jbpm.

Go to Service integration > Buses

Next step is to assign bus members that will host message engine which is essentially application server instance.

Next let's create destinations for our queues, all of type Queue
Go to Service Integration > Busses > {bus name}
Destination resources > Destinations

and create following queues:
Then let's create the actual JMS resources such as Connection factories, Queues, Activation specifications

Connection factories
Create following connection factories to allow integration over JMS
  • KIE.AUDIT - used for audit logging over JMS to make them asynchronous 
  • KIE.RESPONSE.ALL - used for returning replies after processing incoming messages
  • KIE.SESSION - used for incoming message for process operations e.g. start process
  • KIE.TASK - used for incoming messages for task operations e.g. complete task

Create following queues
Activation specification
Create following activation specifications
Worth mentioning is that KIE.AUDIT activation specification should be additionally configured to prevent from processing message concurrently to avoid out of sync messages. Set "Maximum concurrent MDB invocations per endpoint" to 1.

Deploy the application

Upload the WAR file

Go to Applications > Application types > Websphere enterprise applications

Click on Install, select the kie-wb-was8.war file from your local filesystem. Click Next
From here, you will be asked several deployments settings.
You'll need to select the datasource created above as the datasource to be used by the application.

Screen Bind listeners for message-driven beans - select for every bean Activation Specification and fill the corresponding activation specification JNDI name into Target Resource JNDI Name (e.g. jms/activation/KIE.SESSION). You may also specify Destination JNDI name using JNDI name of the appropriate JMS queue (e.g. jms/queue/KIE.SESSION).

We also recommend to set is the context path of the webapp to kie-wb.
Screen Map resource references to resources - for both beans provide JNDI name of KIE.RESPONSE.ALL connection factory (e.g. jms/conn/KIE.RESPONSE.ALL).

Application settings

Go to Applications > Application types > Websphere enterprise applications > kie-wb app > Security role to user/group mapping

Select the five BPMS roles: admin, analyst, developer, manager, user.
Click on Map Special Subjects and select the All Authenticated in Application's Realm option.

Go to Applications > Application types > Websphere enterprise applications > kie-wb app > Class loading and update detection

Ensure the following radio buttons are checked:
  • Classes loaded with local class loader first (parent last)
  • Single class loader for application

Configure SSH GIT server with proper security libraries

Create shared library that will bring in Bouncy Castle library for enhanced security that is required for GIT SSH server to operate properly. Make sure the it will have proper version of bouncy castle defined (tested with bcprov-jdk16-1.46.jar).
Next make a reference to the shared library for the jbpm console application.

Save the configurations to the master and restart the server.

Dashbuilder (BAM) configuration

Follow instructions in this article for installing the dash builder application on WebSphere Application Server.
In addition to this you might want to reduce logging level for class
 - by reduce, set it to war level to avoid spamming your server log whenever this class is used.

This can be done in Troubleshooting -> Logs and trace -> Change log details levels

Very important to note when using both kie-wb and dash builder is that both must use same data base (in come data bases even same data base user) as dash builder depends on tables created and populated by kie-wb so dash builder to work proper (and to actually start the application correctly).

Session management settings

in case of running in combination with dash builder (BAM component) it's is recommended to set following session management property to avoid issues with SSO between kie-wb and dash builder.

Go to:
Application Servers -> {servername} -> Session management -> Custom properties

and add custom property:
name: InvalidateOnUnauthorizedSessionRequestException
value: true

Once restarted you should be able to access the kie-wb application by typing the following URL: http://localhost:9080/kie-wb (unless you used another context root at deploy time).

Have fun and as usual all comments are more than welcome.

20 komentarzy:

  1. I wish I found this site before... I lost so much time...
    Nevertheless trick with jbpm.ut.jndi.lookup set to jta/usertransaction is kind of pity - this is undocumented option of WAS.
    Did you consider use of proper TASK_PERSISTENCE_CONTEXT_MANAGER all the time instead of such workaround ?
    I know that SimpleRuntimeManager.copyEnvironment() misses
    so even if someone finally manages to create proper manager jbpm nukes it all the time, but you should be able to change it.

    1. this is actually not a workaround but needed to be able to lookup user transaction from non managed threads like timers as WAS does not allow JNDI look up from threads that are not managed by application server and thus this thing is needed.
      When it comes to the environment entries they should be now copied (6.2 version).

  2. Hi, we're using jBPM 6.2 to run processes on WAS 8. In one process we use a timer task to wait for a couple of seconds before proceeding with the process. After the timer task the process runs in a new thread. Now the issue is that whenever jBPM want to persist the state of the process (in our DB) this warning occurs: Could NOT lazily initialize session context because of null RequestContext … and therefore the process state cannot be persisted: Could not commit session => WebBeans context with scope type annotation @RequestScoped does not exist within current thread

    DefaultTimerJ W org.drools.core.time.impl.DefaultTimerJobInstance call Unable to execute timer job!

    TimerManager E org.jbpm.process.instance.timer.TimerManager$ProcessJob execute Error when executing timer job
    java.lang.RuntimeException: Unexpected exception executing action org.jbpm.process.instance.event.DefaultSignalManager$SignalAction@dc649186
    javax.persistence.TransactionRequiredException: No active JTA transaction on joinTransaction call

    1. include jbpm-services-ejb-timer jar in your application (or workbench if that is what you ran with) in WEB-INF/lib and then times should be based on ejb timer service and thus have proper transaction context available.

  3. Hi Maciej,
    we replaced Quartz with jbpm-services-ejb-timer but now we got a new error, Do you have any idea?
    Thank you

    [1/22/16 13:36:44:949 CET] 0000004b RegisteredSyn E WTRN0074E: Exception caught from before_completion synchronization operation: javax.ejb.EJBTransactionRolledbackException: nested exception is: javax.ejb.EJBException: See nested exception; nested exception is: java.lang.IllegalStateException: Preparing
    javax.ejb.EJBException: See nested exception; nested exception is: java.lang.IllegalStateException: Preparing
    java.lang.IllegalStateException: Preparing
    at org.jbpm.process.core.timer.impl.GlobalTimerService.getTimerJobInstances(

  4. ah you're on 6.2, there was a small issue with checking the timer validity. It was fixed in 6.3 so you can try using jbpm-services-ejb-timer from 6.3 instead

  5. Hi Maciej

    We put "jbpm-services-ejb-timer from 6.3" into the KIE webapplication, but
    we still got an error "org.drools.persistence.TransactionSynchronizationRegistryHelper putResource Unable to put resource app-updateable-resource value [] due to null 

    Could it be that "DefaultEJBTimerDataSource" is a default DS configured in WAS?
    Because we can see a warning:

    [1/25/16 7:54:38:503 CET] 00000027 PrivExAction W J2CA0144W: No mappingConfigAlias found for ConnectionFactory or DataSource jdbc/DefaultEJBTimerDataSource.
    [1/25/16 7:54:38:507 CET] 00000027 PrivExAction W J2CA0114W: No container-managed authentication alias found for ConnectionFactory or DataSource jdbc/DefaultEJBTimerDataSource.

    Thank you for your help.


    1. don't think the data source matters here. It might be that drools-perssitence-jpa jar in 6.3 had additional changes to make it work as I am 100% sure it does work fine. So you could either try to replace drools-persistence-jpa 6.2 with 6.3 or upgrade entire jbpm to 6.3

  6. Does the JBPM 6.3 run on Websphere 8.0 ? or Websphere 8.5 is required...


    1. never tested it on 8.0 so difficult to say. If you're talking about embedded use case it should work without much hassle. When talking about workbench there might be some CDI related issues but without giving it a go we wouldn't be sure...

  7. Hello,

    I am trying to install “kie-drools-wb-6.3.0.Final-was8.war” on WebSphere V8.5. Do I have to make the entire configuration mentioned above on this article?
    I have already installed the war as an enterprise application with no additional configuration except of the jdbc provider and datasource, as I use IBM DB2 database. I have also changed in the persistence.xml file the lines :


    But the application is not starting .
    Also in the official site for WebSphere there is no file for extra information.

    Thanks in advance for any help

    1. to have fully functional workbench you need to perform all the steps described here.

    2. But some steps are not the same in the procedure described. In the stage "deploy the application" most of the steps described above are missing.

    3. After a lot of search I was finally able to install “kie-drools-wb-6.3.0.Final-was8.war” on WebSphere V8.5 and start it successfully. The problem was that my computer is behind a proxy which refuses connection to github and other resources. So problem solved after put two extra JVM properties:
      1) org.kie.demo: Enables external clone of a demo application from GitHub. This System Property takes precedence over org.kie.example. Default: true . I set it to false
      2)org.kie.example: Enables example structure composed by Repository, Organization Unit and Project. Default: false . I set it to false

  8. property name="" value="update"
    property name="hibernate.dialect" value="org.hibernate.dialect.H2Dialect"
    property name="" value="create"
    property name="hibernate.dialect" value="org.hibernate.dialect.DB2Dialect"

  9. Hi Maciej

    could you please help.
    I am installing KIE 6.3 on Websphere 8.5 Liberty Profile
    and I am getting following error

    Thank you
    [3/1/16 11:09:20:930 CET] 00000059 E CWWKZ0002E: An exception occurred while starting the application jbpm-kie. The exception message was: org.jboss.weld.exceptions.DeploymentException: WELD-001409: Ambiguous dependencies for type ExecutorService with qualifiers @Default
    at injection point [BackedAnnotatedField] @Inject private
    Possible dependencies:
    - Producer Method [ExecutorService] with qualifiers [@Any @Default] declared as [[BackedAnnotatedMethod] @Produces public org.jbpm.executor.cdi.impl.mem.InMemoryExecutorServiceProducer.produceExecutorService()],
    - Producer Method [ExecutorService] with qualifiers [@Any @Default] declared as [[BackedAnnotatedMethod] @Produces public org.jbpm.executor.cdi.impl.jpa.JPAExecutorServiceProducer.produceExecutorService()]

    1. Kristian,

      it was never tested nor designed to work on WAS liberty profile. But anyway what it looks like is missing is the CDI extensions are not invoked as there is an extension that should disable on of these producers based on runtime information - if given class it available or not. And this does not seem to be happening.

      moreover looks like you're using wrong distribution - as there is weld in error message:
      org.jboss.weld.exceptions.DeploymentException: WELD-001409
      while WAS uses OpenWebBeans as far as I know for CDI. Maybe your WAS liberty profile does not have CDI enabled...

    2. Right...You have to explicitly enable CDI, JPA, "concurrency", jaac, el...and probably some others...
      Plus... EjbTimer Service is not supported in LIberty Profile.
      You have to use Quartz wrapper implementing Concurrency Utilities Interface...
      See quartz wrapper examle here:
      I'm working on similar project...trying to deploy KIE Execution Server in OSGi way....It consumes a lot of time...Because Drools marked OSGi-Ready only for theoretical deployment in Fuse Fabric, WLP provides many of required features in completely different way. so I'm still using WB on WildFly for WB tets.

  10. Hi Maciej,

    I'm try it install drools wb on websphere application server for developers, but when i want start the application, there are errors; when i see the SystemOut are the next:
    "[7/11/16 20:46:04:165 CDT] 0000009f ShutdownEvent I notify Shutting down CDI-to-ErraiBus event bridge
    [7/11/16 20:46:04:167 CDT] 0000009f WebContainerL I WebContainerLifecycle afterStopApplication OpenWebBeans Container was stopped for context path, [/kieserver]
    [7/11/16 20:46:04:168 CDT] 0000009f webapp E WebGroup SRVE0015E: Failure to initialize Web application kie-drools-wb-distribution-wars-6.4.0.Final-was8.war
    [7/11/16 20:46:04:218 CDT] 0000009f DeployedAppli W WSVR0206E: Module, kie-drools-wb-distribution-wars-6.4.0.Final-was8.war, of application, kie-wb-war.ear/deployments/kie-wb-war, failed to start
    [7/11/16 20:46:04:221 CDT] 0000009f ApplicationMg W WSVR0101W: An error occurred starting, kie-wb-war
    [7/11/16 20:46:04:221 CDT] 0000009f ApplicationMg A WSVR0217I: Stopping application: kie-wb-war
    [7/11/16 20:46:04:223 CDT] 0000009f SharedEJBRunt I WSVR0041I: Stopping EJB jar: kie-drools-wb-distribution-wars-6.4.0.Final-was8.war
    [7/11/16 20:46:04:228 CDT] 0000009f SharedEJBRunt I WSVR0059I: EJB jar stopped: kie-drools-wb-distribution-wars-6.4.0.Final-was8.war
    [7/11/16 20:46:04:318 CDT] 0000009f ApplicationMg A WSVR0220I: Application stopped: kie-wb-war
    [7/11/16 20:46:04:322 CDT] 0000009f CompositionUn E WSVR0194E: Composition unit WebSphere:cuname=kie-wb-war in BLA WebSphere:blaname=kie-wb-war failed to start.
    [7/11/16 20:46:04:323 CDT] 0000009f MBeanHelper E Could not invoke an operation on object: WebSphere:name=ApplicationManager,process=server1,platform=proxy,node=WIN-3TAN5UOUPEGNode01,version=,type=ApplicationManager,mbeanIdentifier=ApplicationManager,cell=WIN-3TAN5UOUPEGNode01Cell,spec=1.0 because of an mbean exception: Failed to load webapp: Failed to load webapp: The application must supply JDBC connections"

    Can you help me??

  11. as the error suggests, you need to create data source that can be found when application starts. the data source is required to be used by asset mgmt feature but you can use any in memory data source.