Imixs Workflow ...the open source workflow technology for business applications

Engine

Building an Archetype

The Imixs Workflow project provide a sample application called "imixs-workflow-jee-sample". This sample Java EE application can be used as a template to build an Imixs Workflow app. The sample application can be also used to generate a new maven archetype. The Imixs Workflow Project provides such an archetype at:

 org.imixs.application:imixs-workflow-jee-archetype

The following section contains informations about the build process of this kind of archetype.

Note:
It is not necessary to generate a new archetype from the sample application. The following informations are for developers who want to generate a new archetype from the sample application. Please see the Section using Archetypes if you want to start a sample workflow application with maven.

Generating the Archetype from the sample application

To generate a new archetype from the imixs-workflow-jee-sample project you can use the maven archetype plugin calling the 'create-from-project' goal. This goal will generate a new archetype skeleton into the target folder. To call the goal you should work with a maven console (mvn command) at the project folder from the sample application

>cd [project_home]
>mvn archetype:create-from-project

Copy and update the generated Sources

After the maven goal archetype:create-from-project was called the generated sources are located in the folder

 [project_home]/target/generated-sources/archetype/

These sources should now be moved into a new Archetype Project. Optional the sources can also be moved into an existing archetype project like the imixs-workflow-jee-archetype. This update need to be done manually and it is important that all modifications of files are updated carefully into an existing archetype project!

After the first generation some resources need to be modified manually in different file locations. The following section will describe the different files which need to be changed. All resource files to be modified are located under

archetype-metadata.xml

Add the following section to the beginning of the archetype-metadata.xml file to define new required variables. The file is located in 

 [project_home]/target/generated-sources/archetype/src/main/resources/META-INF/maven

This vars are used later in different deployment descriptors to optimize the generated code out from the archetype. 

 <requiredProperties>
        <requiredProperty key="jta-data-source">
                <defaultValue>jdbc/workflow-db</defaultValue>
        </requiredProperty>
        <requiredProperty key="realm">
                <defaultValue>imixsrealm</defaultValue>
        </requiredProperty>
        <requiredProperty key="context-root">
                <defaultValue>workflow</defaultValue>
        </requiredProperty>             
 </requiredProperties>

The 'jta-data-source' variable defines the JTA Data source used by the EJB module defined by the persistence.xml. The 'realm' variable is used in web.xml and sun-web.xml to define the security realm name used by the jee app. The 'context-root' variable defines the web context root where the application can be started using a web browser.

Additional the default variable 'rootArtifactId' is used in some cases described below.

pom.xml (parent module)

In the parent pom.xml the modules section need to be added because it is not generated by the archetype plugin automatically. Edit the pom.xml located at:

 [project_home]/target/generated-sources/archetype/src/main/resources/archetype-resources/pom.xml

Add the following section to the generated pom.xml

....
        <modules>
                <module>${rootArtifactId}-ejb</module>
                <module>${rootArtifactId}-web</module>
                <module>${rootArtifactId}-ear</module>
        </modules>

pom.xml from EAR Module

The pom.xml file from the ear module needs to be modified to replace the module names like shown in the next example because the module names are still hard coded after the archetype generation: 

.....
<modules>
        <webModule>
                <groupId>${groupId}</groupId>
                <artifactId>${rootArtifactId}-web</artifactId>
                <contextRoot>/${context-root}</contextRoot>
        </webModule>
        <ejbModule>
                <groupId>${groupId}</groupId>
                <artifactId>${rootArtifactId}-ejb</artifactId>
        </ejbModule>
.....

persistence.xml from EJB Module

The perstence.xml can be changed to use the jta-data-source variable:

<jta-data-source>${jta-data-source}</jta-data-source>

sun-ejb-jar.xml from EJB Module

In the sun-ejb-jar.xml ther are two changes necessary. First the EJB JNDI Names should be changed to generate unique names depending on the artifact name. And the realm variable should be used to change the realm names used by the web service definitions. Also the web Service endpoints should be change to use teh artifact name in the URI.

.....
        <!-- Imixs Workflow Service EJBs - JNDI Definition -->
        <ejb>
                <ejb-name>EntityServiceBean</ejb-name>
                <jndi-name> ejb/${rootArtifactId}EntityServiceBean </jndi-name>
        </ejb>
        
        <ejb>
                <ejb-name>WorkflowSchedulerBean</ejb-name>
                <jndi-name> ejb/${rootArtifactId}WorkflowSchedulerBean</jndi-name>
                <principal>
                        <name>WorkflowScheduler</name>
                </principal>
        </ejb>
                 
.....

Changing the artefactID

Optional the artefactID for the archetype pom.xml can be changed. For that edit the pom.xml

 [project_home]/target/generated-sources/archetype/pom.xml

..and change the artefactID...

.....
 <artifactId>imixs-workflow-jee-archetype</artifactId>
...

Installing the modified archetype

After all changes are completed the new archetype can be installed locally. This step is only necessary to test the archetype. To install the archetype call simply the install goal from mvn.

To run the install goal successfully its necessary to add the required variables defined in the archetype-metadata.xml with default values. So just edit the file

 [project_home]/target/generated-sources/archetype/src/test/resources/projects/basic/archetype.properties

and add the default values

jta-data-source=jdbc/workflow-db
realm=imixsrealm
context-root=workflow

now you can run the install goal

>cd [project_home]/target/generated-sources/archetype  
>mvn install

After a successful build you should see a message like this:

...generated-sources/archetype$ mvn install
[INFO] Scanning for projects...
[INFO] ------------------------------------------------------------------------
[INFO] Building imixs-workflow-jee-archetype-archetype
[INFO]    task-segment: [install]
[INFO] ------------------------------------------------------------------------
[INFO] [resources:resources {execution: default-resources}]
[WARNING] Using platform encoding (UTF-8 actually) to copy filtered resources, i.e. build is platform dependent!
[INFO] Copying 60 resources
[INFO] [resources:testResources {execution: default-testResources}]
[WARNING] Using platform encoding (UTF-8 actually) to copy filtered resources, i.e. build is platform dependent!
[INFO] Copying 2 resources
[INFO] [archetype:jar {execution: default-jar}]
[INFO] [archetype:add-archetype-metadata {execution: default-add-archetype-metadata}]
[INFO] [archetype:integration-test {execution: default-integration-test}]
/home/rsoika/eclipse/imixs-workflow_v3/imixs-workflow-jee-archetype/target/generated-sources/archetype/target/test-classes/projects/basic/archetype.properties
[INFO] Parent element not overwritten in /home/rsoika/eclipse/imixs-workflow_v3/imixs-workflow-jee-archetype/target/generated-sources/archetype/target/test-classes/projects/basic/project/basic/basic-ejb/pom.xml
[INFO] Parent element not overwritten in /home/rsoika/eclipse/imixs-workflow_v3/imixs-workflow-jee-archetype/target/generated-sources/archetype/target/test-classes/projects/basic/project/basic/basic-web/pom.xml
[INFO] Parent element not overwritten in /home/rsoika/eclipse/imixs-workflow_v3/imixs-workflow-jee-archetype/target/generated-sources/archetype/target/test-classes/projects/basic/project/basic/basic-ear/pom.xml
[INFO] [install:install {execution: default-install}]
[INFO] Installing /home/rsoika/eclipse/imixs-workflow_v3/imixs-workflow-jee-archetype/target/generated-sources/archetype/target/imixs-workflow-jee-archetype-archetype-1.0.0-SNAPSHOT.jar to /home/rsoika/.m2/repository/org/imixs/application/imixs-workflow-jee-archetype-archetype/1.0.0-SNAPSHOT/imixs-workflow-jee-archetype-archetype-1.0.0-SNAPSHOT.jar
[INFO] [archetype:update-local-catalog {execution: default-update-local-catalog}]
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 2 seconds
[INFO] Finished at: Tue Jul 06 22:19:14 CEST 2010
[INFO] Final Memory: 17M/131M
[INFO] ------------------------------------------------------------------------

Create new Project to test the new archetype

Now you can create a new Project form the generated and installed archetype. The maven archetype plugin will ask for group and archetypeID and also for the new defined variables.

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

To generate the new artifact from the local catalog use:

mvn archetype:generate -DarchetypeCatalog=local

Deploy the Archetype on oss.sonatype.org

To deploy the Archetype to oss.sonatype.org repository it is necessary to add the distributionManagement tag to the archetype pom.xml. The pom.xml is located at: 

 [project_home]/target/generated-sources/archetype/pom.xml

Optional a maven-gpg-plugin configuration can also be added. 

 ..
 .....
 .......
 
        <!-- Distributen Management oss.sonatype.org -->
        <distributionManagement>
                <snapshotRepository>
                        <id>sonatype-nexus-snapshots</id>
                        <name>Sonatype Nexus Snapshots</name>
                        <url>http://oss.sonatype.org/content/repositories/snapshots</url>
                </snapshotRepository>
                <repository>
                        <id>sonatype-nexus-staging</id>
                        <name>Nexus Release Repository</name>
                        <url>http://oss.sonatype.org/service/local/staging/deploy/maven2/</url>
                </repository>
        </distributionManagement>
        <profiles>
                <profile>
                        <id>release-sign-artifacts</id>
                        <activation>
                                <property>
                                        <name>performRelease</name>
                                        <value>true</value>
                                </property>
                        </activation>
                        <build>
                                <plugins>
                                        <plugin>
                                                <groupId>org.apache.maven.plugins</groupId>
                                                <artifactId>maven-gpg-plugin</artifactId>
                                                <executions>
                                                        <execution>
                                                                <id>sign-artifacts</id>
                                                                <phase>verify</phase>
                                                                <goals>
                                                                        <goal>sign</goal>
                                                                </goals>
                                                        </execution>
                                                </executions>
                                        </plugin>
                                </plugins>
                        </build>
                </profile>
        </profiles>  
</project>

Run the 'deploy' goal on the archetype

>cd [project_home]/target/generated-sources/archetype  
>mvn deploy