jBPM 6.2 installation and upgrade from previous version

jBPM 6.2 is almost out the door so it's time to give a quick heads up on how to install and upgrade if you already have previous version of jBPM running.

Installation with jBPM installer

the easiest and best way to install jBPM is using jBPM installer that is described in jBPM documentation. It's simple and automated installation process that:

• downloads all required components
• configures services (data source, folder structure, etc)
• bundles the application 
• deploys all applications (jbpm console aka kie workbench and dash builder for BAM)

All is done with ant script so it can be modified in case additional requirements pops up. Most of the information users could be interested in is stored in build.properties file which defines

• version numbers of components to download, 
• container to be used
• data base to be used

So if you're going to try jBPM for the first time, I would recommend to go with this approach.

Installation on Wildfly 8.1.0.Final application server

Another approach would be to configure parts of the application and application server manually on clean or already existing Wildfly server. Following are the steps required:

1. Create data source for jbpm to use - if you want to use default in memory data base that comes with Wildfly server you can skip this step - data source is already defined
1. Create JBoss module for your JDBC driver e.g. org/postgres
2. Edit WILDFLY_HOME/standalone/configuration/standalone-full.xml
3. Define data source for the driver you created e.g. postgres

<xa-datasource jndi-name="java:jboss/datasources/jbpmDS" pool-name="postgresDS" enabled="true" use-java-context="true">
   <xa-datasource-property name="ServerName">
      localhost
   </xa-datasource-property>
   <xa-datasource-property name="PortNumber">
     5432
   </xa-datasource-property>
   <xa-datasource-property name="DatabaseName">
      jbpm
   </xa-datasource-property>
   <driver>postgres</driver>
   <security>
     <user-name>jbpm</user-name>
     <password>jbpm</password>
   </security>
</xa-datasource>

2. Add application users that will be given access to kie workbench
1. Use WILDFLY_HOME/bin/add_user.sh script (or add_user.bat for windows) to add user(s)
1. Use application realm
2. make sure to assign users one or more of following roles: admin,analyst,user,developer,manager
3. Additionally you can assign your user to any other roles that will be used for human task assignments e.g HR,PM,IT,Accounting for HR example process
4. If you would like to use asset management feature that comes with 6.2 assign your user another role called: kiemgmt
3. Download wildfly distribution of the kie workbench for version 6.2.0.Final from here.
4. Extract the war file into WILDFLY_HOME/standalone/deployments/jbpm-console.war
1. You should have all files from the war file inside jbpm-console.war
5. Configure persistence for jbpm console
1. Edit WILDFLY_HOME/standalone/deployments/jbpm-console.war/WEB-INF/classes/META-INF/persistence.xml file
2. Change JNDI name for the data source
3. Change the hibernate dialect for data base you use
6. Create jbpm-console.war.dodeploy empty file inside WILDFLY_HOME/standalone/deployments directory

That's all, now you're ready to start your application server with jbpm console (kie workbench) deployed. To do that go into WILDFLY_HOME/bin and issue following command:

./standalone.sh --server-config=standalone-full.xml

or for windows

./standalone.bat --server-config=standalone-full.xml

NOTE: If you don't have internet access or you don't want to load example repositories from github add following parameter into the server startup command: -Dorg.kie.demo=false

./standalone.sh --server-config=standalone-full.xml -Dorg.kie.demo=false

or for windows

./standalone.bat --server-config=standalone-full.xml -Dorg.kie.demo=false

Upgrade jBPM from 6.1 to 6.2

Upgrading of already existing installation of jBPM console (kie-workbench) that runs with version 6.1 (though from 6.0.1 should be pretty much the same though I haven't tested myself) is quite simple, but requires some steps to be manually executed.

There are some data base changes that must be applied to successfully upgrade workbench to version 6.2 and do not loose any context - like missing deployments, nor not being able to see process or task instances. 

So let's upgrade existing 6.1 environment

1. Shutdown your existing server(s) that run jBPM 6.1 - if there are any running instances
2. Perform data base upgrade
1. jBPM 6.2. comes with upgrade script for commonly used data bases, it can be found as part of jbpm installer/db/upgrade-scripts package or can be taken from gihub.
2. This script contains all data bases so please take only section that applies to your data base (below sql script for postgesql data base as an example)

ALTER TABLE sessioninfo ALTER COLUMN id TYPE bigint;
ALTER TABLE AuditTaskImpl ALTER COLUMN processSessionId TYPE bigint;
ALTER TABLE ContextMappingInfo ALTER COLUMN KSESSION_ID TYPE bigint;
ALTER TABLE Task ALTER COLUMN processSessionId TYPE bigint;

create table DeploymentStore (
    id int8 not null,
    attributes varchar(255),
    DEPLOYMENT_ID varchar(255),
    deploymentUnit text,
    state int4,
    updateDate timestamp,
    primary key (id)
);

alter table DeploymentStore add constraint UK_DeploymentStore_1 unique (DEPLOYMENT_ID);
create sequence DEPLOY_STORE_ID_SEQ;

ALTER TABLE ProcessInstanceLog ADD COLUMN processInstanceDescription varchar(255);
ALTER TABLE RequestInfo ADD COLUMN owner varchar(255);
ALTER TABLE Task ADD COLUMN description varchar(255);
ALTER TABLE Task ADD COLUMN name varchar(255);
ALTER TABLE Task ADD COLUMN subject varchar(255);

-- update all tasks with its name, subject and description
update task t set name = (select shorttext from I18NText where task_names_id = t.id);
update task t set subject = (select shorttext from I18NText where task_subjects_id = t.id);
update task t set description = (select shorttext from I18NText where task_descriptions_id = t.id);

INSERT INTO AuditTaskImpl (activationTime, actualOwner, createdBy, createdOn, deploymentId, description, dueDate, name, parentId, priority, processId, processInstanceId, processSessionId, status, taskId)
SELECT activationTime, actualOwner_id, createdBy_id, createdOn, deploymentId, description, expirationTime, name, parentId, priority,processId, processInstanceId, processSessionId, status, id 
FROM Task;

3. Execute these scripts on your data base - NOTE: make sure that you execute these scripts as schema owner to avoid any permission violation issues one startup
3. Remove jbpm console war file from your application server deployments folder WILDFLY_HOME/standalone/deployments
4. Download wildfly distribution of the kie workbench for version 6.2.0.Final from here.
5. Extract the war file into WILDFLY_HOME/standalone/deployments/jbpm-console.war
1. You should have all files from the war file inside jbpm-console.war
6. Configure persistence for jbpm console
1. Edit WILDFLY_HOME/standalone/deployments/jbpm-console.war/WEB-INF/classes/META-INF/persistence.xml file
2. Change JNDI name for the data source
3. Change the hibernate dialect for data base you use
7. Create jbpm-console.war.dodeploy empty file inside WILDFLY_HOME/standalone/deployments directory - if not already there

That's pretty much all steps that are needed, but before you start the server let me provide you with some changes that are worth noting for 6.2 version that might impact the way it was used.

• in 6.1 all deployment units that were active on the server were stored in system.git repository - which made it workbench specific and quite hidden - 6.2 comes with db based store for information about active deployments. With that, by default storage of deployment unit info are no more persisted into system.git. Though it can be enabled to be still stored in there by using system property: -Dorg.kie.git.deployments.enabled=true
• in 6.1 all operations of Build & Deploy issued from Project Editor caused auto deploy to runtime which was not always desired, this can be disabled using system property: -Dorg.kie.auto.deploy.enabled=false
• in 6.1 redeploy of same version (regardless if that was concrete version or snapshot) was by default allowed, in 6.2 concrete versions must be explicitly undeployed before they can be redeployed. This can be overridden by system property which will allow redeploy for all versions: -Dorg.kie.override.deploy.enabled=true

Now you can start your server and enjoy enhancements and bug fixes that jBPM 6.2 brings in.

 To do that go into WILDFLY_HOME/bin and issue following command:

./standalone.sh --server-config=standalone-full.xml

or for windows

./standalone.bat --server-config=standalone-full.xml

Hope it will be useful and as usually comments are more than welcome.