jharksWorkflow Files

Jharks

WorkflowSurveyEngine version 0.0.5	

Compatible with jharks-workflow-3.0.2

Dependencies/Compatability
- Struts 1.2.x+ 
- Spring 2.5.6
- ehcache 1.5.0
- commons-digester 1.6

1) Download the Jharks workflow-3.0.2.jar and include in your applications library dependencies.
The best approach is to utilize maven so all the underlying library dependencies are automatically handled for you.

2) Download the Jharks workflow-survey-engine-0.0.5.jar and include in your applications library dependencies.

3) Add the key Jharks Workflow Survey Engine action mapping within the Struts config file.

    <action
       path="/jharksContinueWorkflow"
       type="org.jharks.workflow.survey.engine.web.struts.SurveyEngineFrontAction"
       validate="false"
       scope="request"
       >
       <forward name="jharksDynamicSurveyPage" path="jharks_survey_page.tiles" redirect="false"/>
       <forward name="jharksWorkflowEndView" path="jharks_end_page.tiles" redirect="false"/>
    </action>

    - The "path" can be whatever value you want to standardize on within your application.
    - The "type" needs to be set the Jharks Workflow Survey Engine front controller implementation that is part of the workflow-survey-engine jar, org.jharks.workflow.survey.engine.web.struts.SurveyEngineFrontAction.
    - The "validate" attribute should be set to false.
    - The "scope" attribute should be set to false.

Then you basically need to configure two forwards for the action mapping by the standard Jharks names jharksDynamicSurveyPage and jharksWorkflowEndView. 
The example demonstrates these pointing to two tile resources, but these can be just jsp resources as well. 
That will all depend on whether your are using Tiles within your application or not.

You can create the structure yourself for both the jharksDynamicSurveyPage and the jharksWorkflowEndView. 
There is no requirement any specific jharks code than needs to be placed in the jharksWorkflowEndView, 
but there is requirements within the jharksDynamicSurveyPage are the following:

a) You need to make a reference to the Jharks Workflow Survey Engine taglib

<%@ taglib uri="/workflow-survey" prefix="jharks" %>

b) and then you need to include the call to the jharksWorkflowSurvey tag.

<jharks:jharksWorkflowSurvey surveyXml="${requestScope.surveyXml}" path="jharksContinueWorkflow.do"/>

**Note: The path value specified in the tag must match the name you specified within the path attribute of the Struts action mapping.

4) Then you just need to make sure you include in the jharks web resources (javascripts and css files) into your project and make sure you refer to them from within your web pages.

<link rel="stylesheet" type="text/css" href="<c:url value="/jharks/css/jharks-survey-engine.css" />" /> 
<script type="text/javascript" src="<c:url value="/jharks/js/jharksSurveyEngine.js" />"></script>

You will notice the use of jstl tag url within the src and href values. This is the recommended approach to handle the application root context
instead of hard coding it within your references.

5) If you are already using Spring in your application then the next step is easy.  You need to add in the wiring for the Spring components of the Jharks Workflow Survey Engine. The following content needs to be specified in your Spring application context file:

    <bean id="org.jharks.questionGroupConfigCache" class="org.jharks.workflow.survey.engine.cache.EhCacheBasedQuestionGroupCache">
				<property name="cache">
					<bean
						class="org.springframework.cache.ehcache.EhCacheFactoryBean">
						<property name="cacheManager">
							<ref bean="org.jharks.cacheManager"/>
						</property>
						<property name="cacheName" value="org.jharks.questionGroupConfigCache" />
						<property name="eternal" value="false" />
						<property name="overflowToDisk" value="false" />
						<property name="timeToLive" value="86400" />
					</bean>
				</property>
	</bean>
	
	<bean id="org.jharks.cacheManager" class="org.springframework.cache.ehcache.EhCacheManagerFactoryBean"/>
	
	<bean id="org.jharks.questionManager" 
        class="org.jharks.workflow.survey.engine.service.impl.QuestionManagerImpl">
        <property name="questionDao">
          <ref bean="org.jharks.questionDao"></ref>
        </property>
        <property name="questionGroupConfigCache">
          <ref bean="org.jharks.questionGroupConfigCache"></ref>
        </property>
     </bean>
     
     <bean id="org.jharks.responseManager" 
        class="org.jharks.workflow.survey.engine.service.impl.ResponseManagerImpl">
        <property name="responseDao">
          <ref bean="org.jharks.responseDao"></ref>
        </property>
        <property name="answerRetriever">
          <ref bean="org.jharks.answerRetriever"></ref>
        </property>
     </bean>
     
     <bean id="org.jharks.surveyPersistenceManager" class="org.jharks.workflow.survey.engine.service.impl.SurveyPersistenceManagerImpl">
      <property name="surveyPersistenceDao">
        <ref bean="org.jharks.surveyPersistenceDao" />
      </property>
     </bean>
     
     <bean id="org.jharks.xmlDefintionService" class="org.jharks.workflow.survey.engine.service.impl.XmlWorkflowDefinitionServiceImpl">
      <property name="xmlDefinitionDao">
        <ref bean="org.jharks.xmlDefinitionDao"/>
      </property>
  </bean>
    
     <!-- DAO Mappings -->
    <bean id="org.jharks.answerRetriever" class="org.jharks.workflow.survey.engine.web.SurveyAnswerRetrieverRequestImpl"/>
        
    <bean id="org.jharks.questionDao" class="org.jharks.workflow.survey.engine.dao.impl.QuestionJdbcDaoImpl" init-method="populateQuestionIds">
      <property name="dataSource">
        <ref bean="org.jharks.dataSource"/>
      </property>
    </bean>
    
    <bean id="org.jharks.responseDao" class="org.jharks.workflow.survey.engine.dao.impl.ResponseJdbcDaoImpl" init-method="init">
      <property name="dataSource">
        <ref bean="org.jharks.dataSource"/>
      </property>
      <property name="questionDao">
          <ref bean="org.jharks.questionDao"></ref>
        </property>
    </bean>
    
    <bean id="org.jharks.surveyPersistenceDao" class="org.jharks.workflow.survey.engine.dao.impl.SurveyResponseJdbcPersistenceDaoImpl">
      <property name="dataSource">
        <ref bean="org.jharks.dataSource"/>
      </property>
      <property name="questionDao">
        <ref bean="org.jharks.questionDao"/>
      </property>
    </bean>
    
    <bean id="org.jharks.xmlDefinitionDao" class="org.jharks.workflow.survey.engine.dao.impl.XmlWorkflowDefinitionDaoImpl">
      <property name="dataSource">
        <ref bean="org.jharks.dataSource"/>
      </property>
    </bean>
    
    <bean id="org.jharks.dataSource" class="org.springframework.jndi.JndiObjectFactoryBean">
       <property name="jndiName" value="jdbc/**app_datasource**"/>
     </bean>

The one value you will need to specify/change in the above snippet is the jndiName of tje org.jharks.dataSource bean.  You need to appropriately create a datasource within your application server for your web application.  The jndi name you configure for that datasource within your application server must be the value you use within the spring configuration for jharks.

     <defaultCache
        maxElementsInMemory="10000"
        eternal="false"
        timeToIdleSeconds="120"
        timeToLiveSeconds="120"
        overflowToDisk="true"
        diskPersistent="false"
        diskExpiryThreadIntervalSeconds="120"
        memoryStoreEvictionPolicy="LRU"
        />   

You also must add in the ehcache configuration for jharks.  Either add the following entry to your existing ehcache configuration file

or add a file named application-ehcache.xml under WEB-INF/classes in your web application with the content.

    <ehcache xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="ehcache.xsd">
    <diskStore path="java.io.tmpdir"/>
    <!--    <cacheManagerEventListenerFactory class="" properties=""/>-->
    <!--
    Mandatory Default Cache configuration. These settings will be applied to caches
    created programmtically using CacheManager.add(String cacheName).
    The defaultCache has an implicit name "default" which is a reserved cache name.
        
        diskSpoolBufferSizeMB="30"
        maxElementsOnDisk="10000000"
    -->
    <defaultCache
        maxElementsInMemory="10000"
        eternal="false"
        timeToIdleSeconds="120"
        timeToLiveSeconds="120"
        overflowToDisk="true"
        diskPersistent="false"
        diskExpiryThreadIntervalSeconds="120"
        memoryStoreEvictionPolicy="LRU"
        />   
    </ehcache>

6) Add workflow.properties file for the Jharks Workflow Engine to WEB-INF/classes directory within your web application.

    ###########################################
    # Deployment Properties
    ###########################################

    xml-base-directory = etc

    ###########################################
    #Default formats
    default.date.format = MM/dd/yyyy HH:mm

    ###########################################
    # Configuration of value handlers to handle 
    # Answer value objects that are standard java objects
    # other than Strings, or custom value object 
    # implementations.
    #
    ###########################################
    # Standard java classes
    java.util.Date-handler = org.jharks.workflow.handlers.DateValueHandler

    # Custom classes would be entered below

7) The infrastucture and integration should be in place to now start building Jharks surveys within your Struts based web application. 
Now you just need to learn how to create your first Jharks Workflow Definition xml file and define the content (questions for each Survey page).