Monday, November 20, 2017

Deloy imixs-jsf-example on Wildfly



Recently I had occasion to study workflow engines, which led me to “Imixs Workflow”, which is an open source workflow engine for a human-centric business process management (BPM). It has an example application, and here is the guideline http://www.imixs.org/doc/sampleapplication.html to deploy it. Unfortunately, the guideline is not complete or have some errors, below is a complete instruction on how to deploy it on Wildfly. 

Create database

I am using Mysql. Create a database workflow_db, and create a table:
CREATE TABLE `DOCUMENT` (
  `ID` varchar(255) NOT NULL,
  `CREATED` datetime DEFAULT NULL,
  `DATA` longblob,
  `MODIFIED` datetime DEFAULT NULL,
  `TYPE` varchar(255) DEFAULT NULL,
  `VERSION` int(11) DEFAULT NULL,
  PRIMARY KEY (`ID`)
) ENGINE=InnoDB DEFAULT CHARSET=latin1;


Install wildfly

Download wildfly from http://wildfly.org/downloads/ and unzip it somewhere. The current version is 11.0.0.Final. 

Configure wildfly

Configure datasource

1)      Download mysql jdbc driver mysql-connector-java-5.1.25.jar and put it into standalone\deployments.

The official guideline says mysql-connector-java-5.1.7-bin.jar, there is a bug in that jar which will cause the application to throw out “error in sql syntax”.  

2)      Edit standalone.xml and Add the following into <datasources>:
<datasource jta="true" jndi-name="java:/jdbc/workflow-db" pool-name="workflow-db" enabled="true" use-ccm="true">
                    <connection-url>jdbc:mysql://192.168.33.10:3306/workflow_db</connection-url>
                    <driver-class>com.mysql.jdbc.Driver</driver-class>
                    <driver>mysql-connector-java-5.1.25.jar</driver>
                    <security>
                        <user-name>…</user-name>
                        <password>…</password>
                    </security>
                    <validation>
                        <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLValidConnectionChecker"/>
                        <validate-on-match>true</validate-on-match>
                        <background-validation>false</background-validation>
                    </validation>
</datasource>

3)      The Imixs-Sample Application uses EclipseLink for JPA. Download EclipseLink from https://www.eclipse.org/eclipselink/downloads/, and put it under modules/system/layers/base/org/eclipse/persistence/main.

Edit the file module.xml located at the same location and change:
    <resources>
        <resource-root path="jipijapa-eclipselink-11.0.0.Final.jar"/>
    </resources>

To:

    <resources>
        <resource-root path="jipijapa-eclipselink-11.0.0.Final.jar"/>
            <resource-root path="eclipselink.jar">
            <filter>
                        <exclude path="javax/**" />
            </filter>
        </resource-root>
</resources>

      Edit standalone.xml and add the following:
<system-properties>
        <property name="eclipselink.archive.factory" value="org.jipijapa.eclipselink.JBossArchiveFactoryImpl"/>
</system-properties>

system-properties is a top level element, you can add it right next to the <extensions> element.

Configure security

Add 3 property files under standalone\configuration.

sampleapp-users.properties:
manfred=password1
anna=password2

sampleapp-roles.properties:
manfred=IMIXS-WORKFLOW-Manager
anna=IMIXS-WORKFLOW-Author

imixsrealm.properties:
IMIXS-WORKFLOW-Reader=org.imixs.ACCESSLEVEL.READERACCESS
IMIXS-WORKFLOW-Author=org.imixs.ACCESSLEVEL.AUTHORACCESS
IMIXS-WORKFLOW-Editor=org.imixs.ACCESSLEVEL.EDITORACCESS
IMIXS-WORKFLOW-Manager=org.imixs.ACCESSLEVEL.MANAGERACCESS

Edit standalone.xml and add the following under <subsystem xmlns="urn:jboss:domain:security:2.0">/ <security-domains>:
<security-domain name="imixsrealm">
        <authentication>
               <login-module code="UsersRoles" flag="required">
                      <module-option name="usersProperties" value="${jboss.server.config.dir}/sampleapp-users.properties"/>
                       <module-option name="rolesProperties" value="${jboss.server.config.dir}/sampleapp-roles.properties"/>
                 </login-module>
                 <login-module code="RoleMapping" flag="required">
                         <module-option name="rolesProperties" value="file:${jboss.server.config.dir}/imixsrealm.properties"/>
                           <module-option name="replaceRole" value="false"/>
                   </login-module>
           </authentication>
 </security-domain>

Configure the example application

This step is not mentioned in the official guideline at all.

Edit imixs-jsf-example-4.0.10.war/ jboss-web.xml, change:
               <resource-ref>
            <res-ref-name>mail/org.imixs.workflow.mail</res-ref-name>
            <res-type>javax.mail.Session</res-type>
            <jndi-name>java:/mail/org.imixs.workflow.mail</jndi-name>
      </resource-ref>

To:
<env-entry>
<description> Mail Plugin Session name</description>
<env-entry-name>IMIXS_MAIL_SESSION</env-entry-name>
<env-entry-type>java.lang.String</env-entry-type>
<env-entry-value>mail/org.imixs.workflow.mail</env-entry-value>
</env-entry>
<resource-ref>
<res-ref-name>java:/mail/org.imixs.workflow.mail</res-ref-name>
<res-type>javax.mail.Session</res-type>
<res-auth>Container</res-auth>
<res-sharing-scope>Shareable</res-sharing-scope>
</resource-ref>

Deploy

Now you can copy imixs-jsf-example-4.0.10.war to standalone\deployments, and start it using bin\standalone.bat. You can now access http://localhost:8080/workflow using one of the users defined in a property file.

Below is some screenshot to showcase the workflow engine’s capabilities. Notice the workflow section which has buttons that drives the process: