But back to the importance of the overwrite-worfklow element in identity-ui-configuration.xml. By default when you first add a new process xml file to the /jboss-portal-ha.sar/portal-identity.sar/con/processes directory, it will be picked up by the portal server on its next restart and loaded into its jbpm database. This can lead you to believe that if the portal server is smart enough to recognize a new process has been deployed then it will be smart enough to recognize that the process has been updated too. Therefore simply overwriting the process definition file will upload a new definition to the database right?

Wrong. Unfortunately the server can only detect new process definition files in that directory, and won’t examine existing ones to look for changes. To have the portal server update existing processes that have already been deployed you must set overwrite-workflow to true. However as described in the documentation overwrite-workflow does not function just quite how you might like.

As it states, it overwrites existing process definitions, but that means that it will deploy new versions of all the process definitions that exist rather than examining them and determining which of them really need to be updated. So even if your process definition has not changed, it will deploy a new version.

Of course this may not matter as jbpm versions all the process definitions in the database, and any suspended or inflight process instances continue to run using the version of the process definition that they started with. Production instances of portal are (hopefully) rarely restarted and therefore will rarely deploy new process instances. But there are a couple of gotchas to watch out for.

Portal is frequently restarted during the development phase, often several times a day. This can lead to the jbpm database quickly having many versions of all the process definitions, which in turn can lead to some interesting problems trying to debug issues as it may not be possible to easily relate a process instance to a process definition xml file. This problem will be worsened if the portal database is shared between several developers.

In production, Portal is often clustered. If overwrite-workflow is set to true on all the portal instances then new definition versions will be deployed when each of the portal instances are restarted. This could quickly become a problem if there are many instances or if the portal server needs to be restarted outside of planned maintenance windows. In production there could well be a large number of running process instances that may need to be related back to a particular version for diagnostic purposes.

What can be done?

The simplest solution is to set overwrite-workflow to true only when you actually have new versions of the process definition files to deploy. The downsides of this approach are that it will deploy new versions of all the processes found in the directory, regardless of whether or not they have changed, and that you must remember to keep toggling the switch on and off.

For clustered production nodes, I recommend that during an upgrade process one instance is taken down and used to update the process definitions. After which the setting is immediately set to false again. The same configuration file can be used on all the instances, as its only ever modified briefly during the upgrade of one portal server instance. It should be noted though that if your new definition requires some updated code that you are also deploying, you may well need to take down all of the instances.

Summary

In brief, the original problem was that JBoss portal does not pick up updated instances of jbpm process definitions in the /jboss-portal-ha.sar/portal-identity.sar/conf/processes directory. It will only detect process definition files there the first time they are copied there. Subsequent updates to those files will not be deployed.

A workaround/correction to this issue is to set overwrite-workflow to true in identity-ui-configuration.xml. However this has the side-effects of redeploying all the process definitions in the directory, and continuing to redeploy them each time the portal is restarted, potentially leading to a large number of process definition versions in the database.