Imixs Workflow ...the open source workflow technology

JSF Tools

Using the JSF Tools Archetype

The Imixs JSF Tools provide an example jsf application called "imixs-workflow-jsf-sample". This sample jee web application can be used as a template to build an Imixs JEE Workflow app.

This user guide shows how to create and setup a JEE Workflow Application with Eclipse and Maven using the Imixs JSF Sample Archetype.

When using Maven it is mostly easy to setup a new Imixs workflow project as this project provides a Maven archetype. A Maven archetype is kind of template or scaffold to build an new project. General informations about using maven in conjunction with imixs workflow can be found here.

The following user guide will explain how you can setup a new workflow project with Eclipse an Maven

Note:
This user guide assumes that you are working with Eclipse IDE and you have installed the Eclipse Maven2 Plugin. You can also setup a new project form this archetype using the maven standard command line tool with any other IDE. The usage of the maven command line tool will be explained at the end of this documentation. If you are using the Eclipse Maven Plugin it is not necessary to download and install maven apart, as maven is included in the Eclipse Maven Plugin. Additional Informations about using Imixs Workfow with Maven can be found here.

Add the java.net Repository Index

The Imxis Workflow Project is hosted on java.net. So first make sure that the java.net Maven repoistory is listed in your Eclipse Repository View. You can check the configured Maven repositories when you open the Eclipse view "Maven Indexes"

If the java.net Maven repository is not listed there you can add a new maven repository.

Click "Add Index" to add the java.net Maven repository 'http://download.java.net/maven/2/'

Create a new Project

Using the Maven Eclipse Plugin makes is really easy to setup a new maven project form an archetype.

Click "File->New->Project" and select the Maven Project Wizard

Next page in the wizard click next to choose an Maven Archetype from one of the repositories:

The Nexus Catalog provides you with all Archetypes provided from the Maven repository locations. To find the Imixs JSF Sample Archetype enter "org.imixs" in the filter input filed:

select the imixs-workflow-jsf-sample-archetype and klick next.

On the following wizard page you can specify the Group and Artifact ID of your new project and also configure additional project settings:

The Imixs JSF Sample Archetype provides three property values which allows you to configure your project setup. All settings can be changed also afterwards but you are much faster if you specify this properties during the creation process

jta-data-source

The jta data source specifies the JNDI Name of your JDBC datasource resource configured by your application server. This JDBC resource will be used by the Imixs Workflow System to store data into a database. The default value is 'jdbc/workflow'. This value can be later changed in the persistence.xml of the EJB module.

realm

The realm defines the security realm name to be used authenticating users. A security realm is configured in the application server. The default value is 'imixsrealm'. This value can be later changed in the web and ejb deployment descriptor files.

context-root

The context-root defines the name of the web module to be used to start the application. The default value is "workflow" so the URL where the application can be started is http://localhost:8080/workflow/

Complete the project setup

After all settings are completed click finish to create and setup the new JSF Workflow project. Maven will create a new Multi-Module Project containing all necessary parts of a JEE Application.

Unfortunately there is a bug in the Eclipse Maven plugin that prevents file filtering and so the project folders of the EJB, Web and EAR Moduls stay called e.g. _rootArtifactId_-web. (See MNGECLIPSE-1054).

Using the Maven command line tool

As mentioned before there is unfortunately a bug in the Eclipse Maven Plugin which generates wrong folder names. So to prevent this you can optional use the maven command line instead of the Eclipse maven plugin.

This is also a mostly an easy way to setup a working project configuration with maven. Of course you need to have a working maven setup. Please refer to the maven home page for a description of how to install and setup maven.

Add the java.net repository to your maven settings.xml to let maven download archetypes and artifacts from java.net

...
<repositories>
 .....
        <repository>
                <id>java.net</id>
                <url>http://download.java.net/maven/1</url>
                <layout>legacy</layout>
        </repository>
...

You can create a new Imixs JSF Workflow project by executing the following command 

mvn archetype:generate -DarchetypeGroupId=org.imixs.workflow -DarchetypeArtifactId=imixs-workflow-jsf-sample-archetype -DarchetypeVersion=0.0.1-SNAPSHOT

After the execution you have to can configure several initialization parameters for your new project:

  • Give a dot separated Group Id. e.g. com.mycompany
  • Give a ArtifactId e.g. MyWorkflowApp
  • Confirm the suggested version number (e.g. 1.0-SNAPSHOT)
  • Give a dot separated package name e.g. org.example.myexample
  • Give new values for the jta-data-source, realm, and context-root properties as describe above.
  • Confirm your settings

You should see a "BUILD SUCCESSFUL" and a "com.mycompany.MyWorkflowApp" folder with 3 projects inside:

  • MyWorkflowApp-ear (The EAR project)
  • MyWorkflowApp-ejb (The EJB 3.0 Module)
  • MyWorkflowApp-web (The JSF Web application)

Execute 'mvn install' to install the parent pom to your local repository.

After this you can also import the whole project into eclipse with File -> Import... -> General -> Existing Projects into Workspace and continue working with your new Imixs Workflow Project