If we go on tour together with Oracle I think we have to have camunda BPM running on the Oracle WebLogic application server 12c (WLS in short). And one of our enterprise customers asked - so I invested a Sunday and got it running (okay - to be honest - I needed quite some help from our Java EE server guru Christian). In this blog post I give a step by step description how run camunda BPM on WLS. Please note that this is not an official distribution (which would include a sophisticated QA, a comprehensive documentation and a proper distribution) - it was my personal hobby. And I did not fire the whole test suite agains WLS - so there might be some issues. We will do the real productization as soon as we have a customer for it (let us know if this is interesting for you).
Necessary steps
After installing and starting up WLS (I used the zip distribution of WLS 12c by the way) you have to do:
- Add a datasource
- Add shared libraries
- Add a resource adapter (for the Job Executor using a proper WorkManager from WLS)
- Add an EAR starting up one process engine
- Add a WAR file containing the REST API
- Add other WAR files (e.g. cockpit) and your own process applications
Actually that sounds more work to do than it is ;-) So let's get started:
Add a datasource
Add a datasource via the Administration Console (or any other convenient way on WLS - I should admit that personally I am not the WLS expert). Make sure that you target it on your server - this is not done by default:
Which camunda distribution do I use?
Before we can install the camunda BPM platform on WLS we have to download it. But there is no WLS distribution yet. Hence we can leverage the existing distributions for other Java EE containers, I use the Glassfish distribution as it is technically pretty close to WLS.
Unfortunately I had small issues with the current alpha3 version on WLS - which I fixed on a branch and try to convince the team to apply them to alpha4. So for the moment you have to build a patched alpha3 from this branch: https://github.com/camunda/camunda-bpm-platform/tree/wls-prototype-7.0.0-alpha3/distro/wls12c. If you do not want to build it by hand here is a ZIP file containing the relevant artifacts:
Now we will install the artifacts step by step.
Add shared libraries
Just copy the provided libraries (the core engine, necessary dependencies like Apache MyBatis and interfaces for the Ressource Adapater) into your domain "lib" folder:
Add resource adapater
We use a JCA (Java EE Connector Architecture) resource adapter to be fully Java EE compliant. This component is basically responsible to do something we call Job handling. Basically we need a thread pool to query the database if any timers or the like are due. See more details in the Job Executor docs.
The resource adapter is deployed as RAR archive. I used the archive provided for Glassfish - as there are no changes necessary. You can deploy it via the Administration Console without problems:
The resource adapter is deployed as RAR archive. I used the archive provided for Glassfish - as there are no changes necessary. You can deploy it via the Administration Console without problems:
Important: You now have to adjust the configuration. Change the deployment order (the resource adapter should be deployed before other stuff), set a JNDI name and allow global access to classes (actually I still wonder how providing the RAR classes to EAR classloaders really works in WLS as defined in the JCA specs - I didn't get it to work in the prototype so I added the stuff as shared libraries - any hints from WLS experts are welcome!):
And you have to provide an outbound connection factory which later can be used via JNDI from our process engine:
And last but not least we need a Weblogic WorkManager for our thread pool:
That's it. Next step :-)
Add EAR starting a process engine
I have build a custom EAR for WLS to provide a WLS specific deployment descriptor necessary to wire the EAR with the RAR correctly - but I will skip the details here. The EAR basically only does one thing: It starts up one engine - therefor it does not have more content than the deployment descriptor and a "bpm-platform.xml" file containing the configuration of that process engine. Deploy this with the wizard again:
This time there is not much to configure - I would suggest that you change the deployment order to 75 - then it gets deployed after the RAR but before other applications.
If you want - you can have a look in the JNDI tree - you should see the started process engine there:
Deploy REST API as WAR
Now we can deploy the REST API, this is a simple WAR (leveraging JAX-RS) providing a REST interface to the already running process engine of the server. To be precise it provides an interface to all running process engines of the current server - but that's a story for a different post :-)
You can deploy the WAR file (I again used the Glassfish one without modifications) with the wizard - I think you practiced that enough by now. Just make sure you deploy it as "application" - not as "library" as the wizard tried to trick me here.
For example you can now query all existing process engines: http://localhost:7001/engine-rest/engine/. You can see get the one existing engine:
Congratulations - now on you have a platform working correctly within WLS - fully Java EE 6 compliant - and without any hazzle for starting your process engine. Amazing - isn't it?
Deploy cockpit and tasklist
Since tasklist and cockpit are HTML5 web applications using the REST API in the background you can easily deploy them as well as soon as you have the REST API running. Do that now (use the wizard again) and you can access them via the browser:
- http://localhost:7001/cockpit/
- http://localhost:7001/tasklist/ (I locally had a strange problem during login - it basically only worked with Chrome at the moment. Unfortunately no time to dig deeper - but at latest when we productize it we will figure that out! Or you do :-)).
Deploy Process Applications
Now you can deploy normal process applications - as e.g. described in the Getting Started Guide. Enjoy!
Please note that there is one limitation with the current codebase on WLS: The classpath scanning we do in order to find process definition files automatically does not work on WLS. Hence you can not auto-discover your process definitions but have to configure them by hand in the META-INF/processes.xml:
<process-application
xmlns="http://www.camunda.org/schema/1.0/ProcessApplication"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<process-archive name="pa">
<process-engine>default</process-engine>
<process>invoice.bpmn</process>
<properties>
<property name="isDeleteUponUndeploy">false</property>
<property name="isScanForProcessDefinitions">false</property>
</properties>
</process-archive>
</process-application>
Some Screenshots
To prove that it was working :-) See cockpit showing the invoice example process application:
The tasklist:
And starting a process instance via REST:
Feedback welcome
We welcome every feedback on this - best use our forum (http://camunda.org/community/forum.html, can be used by sending mails to it as well: camunda-bpm-users@googlegroups.com). Let us now if you want to use this in production - then we can place a proper enterprise distribution on our roadmap...