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
- kie.services.jms.queues.response set to jms/KIE.RESPONSE.ALL
- kie.services.rest.deploy.async set to false
-
-
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
Go to Users and groups > Manage users
Create a single user and add to selected groups above.
Register the SSL certificate from Github.com
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: Host=github.com, Port=443, Alias=github.com
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:
- KIE.AUDIT
- KIE.RESPONSE.ALL
- KIE.SESSION
- KIE.TASK
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
Queues
Create following queues
- KIE.AUDIT
- KIE.RESPONSE.ALL
- KIE.SESSION
- KIE.TASK
Activation specification
Create following activation specifications
- KIE.AUDIT
- KIE.RESPONSE.ALL
- KIE.SESSION
- KIE.TASK
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
com.ibm.websphere.rsadapter.WSCallHelper
- 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.
