Kuali Rice 0.0.17-test Technical Reference Guide

In addition to programmatically acquiring service references, you can also import Rice services into a Spring context with the help of the ResourceLoaderServiceFactoryBean:

<!-- import a Rice service from the ResourceLoader stack -->
<bean id="aRiceService" class="org.kuali.rice.resourceloader.support.ResourceLoaderServiceFactoryBean"/>

This class uses the GlobalResourceLoader to locate a service named the same as the ID and produces a bean that proxies that service. The bean can thereafter be wired in Spring like any other bean.

Rice includes a Spring bean that extends the Spring auto-wire process (unlike the current version of Spring, the auto-wire process in the version of Spring that’s included with Rice cannot be extended). With this bean configured into your application, you can use the @RiceService annotation to identify Rice services to auto-wire.

Add this bean definition to the top of your Spring configuration file to configure the Spring extension:

<bean class="org.kuali.rice.core.util.GRLServiceInjectionPostProcessor"/>

Add the @RiceService annotation to any field or method, following the normal Spring rules for injection annotations. The annotation requires a name property that specifies the name of the service to inject. If the name requires a namespace other than the current context namespace, you must specify the namespace as a prefix (for example, “{KEW}actionListService”).

@RiceService(name="workflowDocumentService")
protected WorkflowDocumentService workflowDocumentService;

In certain cases, it may be desirable to publish all beans in a particular Spring context to the Resource Loader stack. Fortunately, there is an easy way to accomplish this using the RiceSpringResourceLoaderConfigurer as shown below:

<!—- Publish all services from this Spring context to the GRL -->
<bean class="org.kuali.rice.core.resourceloader.RiceSpringResourceLoaderConfigurer"/>

<bean id="myService1" class="my.app.package.MyService1"/>

<bean id="myService2" class="my.app.package.MyService2"/>

In the above example, both myService1 and myService2 would be added to a Resource Loader that would be put at the top of the Resource Loader stack. The names of these services would be “myService1” and “myService2” with no namespace. To load these services you would use the following call to the Global Resource Loader:

MyService1 myService1 = GlobalResourceLoader.getService(“myService1”);

The driver for MySQL is already referenced by the Kuali Rice project. Rice does not have out-of-the-box support for other RDBMS at this point in time. However, if you want to use other databases, it is possible to add database support for that particular database as long as it’s supported by the Apache OJB project (http://db.apache.org/ojb).

If this is the first time that you have installed the Maven plugin into your Eclipse environment, you may need to add a file called settings.xml in your <user home>/.m2 directory.

The easiest way to tell if you need to do this is that there will be a warning in the console after building, stating that the settings.xml file is missing. All you need to do is create a settings.xml file with this content:

<settings/>

Rebuild, and the warning should no longer appear.

If your default workspace JDK is not 1.5, you need to reconfigure the Maven external tools definitions for Rice this way:

The default Maven2 repository location is in your user directory; however, if you have a pre-existing repository (or for some other reason don't want it in your user directory), you can alter Maven2's repository location. The current version of the Maven2 plugin has a bug that does not allow this to work (see http://jira.codehaus.org/browse/MNGECLIPSE-314), but the 0.0.11 development version available from the update site http://m2eclipse.codehaus.org/update-dev/ allows you to specify a custom local repository.

If your default workspace JDK is not 1.5, then you also need to set the JDK compliance level to the appropriate version for the project. You can find this by right-clicking on the Project -> Properties -> Java Compiler -> Compiler compliance level. Be sure the Enable project specific settings checkbox is checked.

Be sure to turn off validation at the project level by right-clicking on the Project, then clicking Properties -> Validation -> Suspend all Validators. This can be adjusted once a successful Rice project is up and running.

If you start seeing java.sql.SQLException: Listener refused the connection with the following error: ORA-12519, TNS:no appropriate service handler found, there are a couple of things that may remedy the problem.

Disconnect any other clients and then restart Oracle-XE.

To get ready to run the script:

Enter groovy createproject.groovy followed by one or more of the following parameters, separated by spaces:

groovy createproject.groovy -name MyFirstProject -sampleapp

Further instructions on how to open the project and run it will be printed to the console when the script has finished executing. At this point, you now have a skeleton of a Kuali Rice client application that you can use to begin building your own application. However, before running the application, you will need to create a Rice database (if you’re using the sampleapp, you’ll need to set up the demo database; otherwise, you’ll set up a stripped-down bootstrap database).

The configuration of this application uses a bundled model where the Rice server and client pieces are all being included and loaded by your sample application. This is useful for development purposes since it makes it very easy to get the application running. It is not recommended for an enterprise deployment where you may want to have more than one application integrating with Kuali Rice. In these cases, you would want to install and integrate with a Standalone Rice server. For more information on installing and configuring a standalone server, see the Installation Guide.

Below is an example of a configuration XML file. Note that the white space (spaces, tabs, and new lines) is stripped from the beginning and end of the values.

<config>
    <param name="client1.location">/opt/jenkins-home/jobs/rice-trunk-release/workspace/target/checkout/src/test/clients/TestClient1</param>
    <param name="client2.location">/opt/jenkins-home/jobs/rice-trunk-release/workspace/target/checkout/src/test/clients/TestClient2</param>
    <param name="ksb.client1.port">9913</param>
    <param name="ksb.client2.port">9914</param>
    <param name="ksb.testharness.port">9915</param>
    <param name="threadPool.size">1</param>
    <param name="threadPool.fetchFrequency">3000</param>
    <param name="bus.refresh.rate">3000</param>
    <param name="keystore.alias">rice</param>
    <param name="keystore.password">super-secret-pw</param>
    <param name="keystore.file">/opt/jenkins-home/jobs/rice-trunk-release/workspace/target/checkout/src/test/resources/keystore</param>
</config>

Here is an example of the Java code required to parse the configuration XML file and convert it into a Properties object:

Config config = new SimpleConfig(configLocations, properties);
config.parseConfig();             

In the sample above, configLocations is a List<String> containing file locations using the standard Spring naming formats (examples: file:/whatever and classpath:/whatever). The variable properties is a Properties object containing the default property values.

Here is an example of retrieving a property value from Java code:

String val = ConfigContext.getCurrentContextConfig().getProperty(“keystore.alias”);

The Rice Configuration System has a special parameter, config.location, which you use to incorporate the contents of another file. Typically, you use this to include parameters that are maintained by system administrators in secure locations. The parameters in the included file are parsed as if they had been in the original file at that place. Here is an example:

<config>
    <param name="config.location">file:/my_secure_dir/my_secure_file.xml</param>
</config>

Once you have defined a parameter, you can use it in the definition of another parameter. For example:

<config>
    <param name="apple">red delicious</param>
    <param name="taste">yummy yummy</param>
    <param name="apple.taste">${apple} ${taste}</param>
</config>

When this example is parsed, the value of the parameter apple.taste will be set to red delicious yummy yummy.

Because the parameters are converted into a Properties object, you can retrieve the complete list of parameters using this code:

config.getProperties()

You typically use this in Spring to parse a configuration and put its properties in a PropertyPlaceHolderConfigurer so that the parameters are available in the Spring configuration file:

<bean id="config" class="org.kuali.rice.core.config.spring.ConfigFactoryBean">
    <property name="configLocations">
        <list>
            <value>classpath:my-config.xml</value>
        </list>
    </property>
</bean>

<bean id="configProperties"
 class="org.springframework.beans.factory.config.MethodInvokingFactoryBean">
    <property name="targetObject" ref="config" />
    <property name="targetMethod" value="getProperties" />
</bean>

<bean class="org.springframework.beans.factory.config.PropertyPlaceholderConfigurer">
    <property name="properties" ref="configProperties" />
</bean>

Once this is complete, the configuration parameters can be used like standard Spring tokens in the bean configurations:

<bean id="dataSource" class="org.kuali.rice.core.database.XAPoolDataSource">
    <property name="transactionManager" ref="jotm" />
    <property name="driverClassName" value="${datasource.driver.name}" />
    <property name="url" value="${datasource.url}" />
    <property name="maxSize" value="${datasource.pool.maxSize}" />
    <property name="minSize" value="${datasource.pool.minSize}" />
    <property name="maxWait" value="${datasource.pool.maxWait}" />
    <property name="validationQuery" value="${datasource.pool.validationQuery}" />
    <property name="username" value="${datasource.username}" />
    <property name="password" value="${datasource.password}" />
</bean>

The Config object can be injected into the RiceConfigurer that’s configured in Spring and it will initialize the configuration context with those configuration parameters.

This is done as follows:

<bean id="config" class="org.kuali.rice.core.config.spring.ConfigFactoryBean">
    ...
</bean>

<bean id="rice" class="org.kuali.rice.core.config.RiceConfigurer">
    <property name=”rootConfig” ref=”config”/>
</bean>

The primary purpose of overriding configuration values is to provide a set of default values in a base configuration file and then provide a separate file that overrides the values that need to be changed. You can also update a parameter value multiple times in the same file. Parameter values can be changed any number of times; the last value encountered while parsing the file will be the value that is retained.

For example, when parsing the file:

<config>
    <param name="taste">yummy yummy</param>
    <param name="taste">good stuff</param>
</config>

The final value of the parameter taste will be good stuff since that was the last value listed in the file.

As another example, when parsing the file:

<config>
    <param name="taste">yummy yummy</param>
    <param name="apple.taste">apple ${taste}</param>
    <param name="taste">good stuff</param>
</config>

The final value of the parameter apple.taste will be apple yummy yummy. This demonstrates that parameters that appear in the value are replaced by the current value of the parameter at that point in the configuration file.

Additionally, you can define certain parameters in such that they won’t override an existing parameter value if it’s already set.

As an example of this, consider the following configuration file:

<config>
    <param name="taste" override=”false”>even yummier</param>
    <param name=”brand.new.param” override=”false”>brand new value</param>

</config>

If this file was loaded into a configuration context that had already parsed our previous example, then it would notice that the taste parameter has already been set. Since override is set to false, it would not override that value with even yummier. However, since brand.new.param had not been defined previously, it’s value would be set.

Configure the JOTM transaction manager and user transaction objects as Spring beans in your application’s Spring configuration file. Here is an example:

<bean id="jotm" class="org.springframework.transaction.jta.JotmFactoryBean">
    <property name="defaultTimeout" value=”3600”/>
</bean>
    
<alias name="jotm" alias="jtaTransactionManager"/>
<alias name="jotm" alias="jtaUserTransaction"/>

You can use these beans in the configuration of Spring’s JTA transaction manager and the Rice configurer. This configuration might look like the following:

<bean id="springTransactionManager" class="org.springframework.transaction.jta.JtaTransactionManager">
    <property name="userTransaction">
        <ref local="userTransaction" />
    </property>
    <property name="transactionManager">
        <ref local="jtaTransactionManager" />
    </property>
</bean>    

<bean id="rice" class="org.kuali.rice.core.config.RiceConfigurer">
    <property name="transactionManager" ref="jtaTransactionManager" />    
    <property name="userTransaction" ref="jtaUserTransaction" />
    ...
</bean>

JTA requires that the datasources that are used implement the XADataSource interface. Some database vendors, such as Oracle, have pure XA implementations of their datasources. However, internally to Rice, we use wrappers on plain datasources using a library called XAPool. When configuring transactional data sources that will be used within JOTM transactions, you should use the org.kuali.rice.core.database.XAPoolDataSource class provided with Rice. Here is an example of a Spring configuration using this data source implementation:

<bean id="myDataSource" class="org.kuali.rice.core.database.XAPoolDataSource">
    <property name="transactionManager" ref="jtaTransactionManager" />
    <property name="driverClassName" value="${datasource.driver.name}" />
    <property name="url" value="${datasource.url}" />
    <property name="maxSize" value="${datasource.pool.maxSize}" />
    <property name="minSize" value="${datasource.pool.minSize}" />
    <property name="maxWait" value="${datasource.pool.maxWait}" />
    <property name="validationQuery" value="${datasource.pool.validationQuery}" />
    <property name="username" value="${datasource.username}" />
    <property name="password" value="${datasource.password}" />
</bean>

When using the built-in instance of the Quartz scheduler that Rice creates, you will need to inject a non-transactional data source into the RiceConfigurer in addition to the JTA transactional instance. This is to prevent deadlocks in the database and is required by the Quartz software (the Quartz web site has an FAQ entry with more details on the problem). Here is an example of a non-transactional data source configuration:

<bean id="nonTransactionalDataSource"
 class="org.apache.commons.dbcp.BasicDataSource" destroy-method="close">
    <property name="driverClassName" value="${datasource.driver.name}"/>
    <property name="url" value="${datasource.url}"/>
    <property name="maxActive" value="${datasource.pool.maxActive}"/>
    <property name="minIdle" value="7"/>
    <property name="initialSize" value="7"/>
    <property name="validationQuery" value="${datasource.pool.validationQuery}"/>
    <property name="username" value="${datasource.username}" />
    <property name="password" value="${datasource.password}" />
    <property name="accessToUnderlyingConnectionAllowed"
 value="${datasource.dbcp.accessToUnderlyingConnectionAllowed}"/>
</bean>

You need to either inject this non-transactional data source into the Quartz SchedulerFactory Spring bean (if you are explicitly defining it) or into the rice bean in the Spring Beans config file as follows:

<bean id="rice" class="org.kuali.rice.config.RiceConfigurer">
    ...
    <property name="nonTransactionalDataSource" ref="nonTransactionalDataSource" />
    ...
</bean>

<?xml version="1.0" encoding="UTF-8"?>
<!-- A Simple Notification Message -->
<notification xmlns="ns:notification/NotificationRequest"
    xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance
    xsi:schemaLocation="ns:notification/NotificationRequest
    resource:notification/NotificationRequest">
    <!-- this is the name of the notification channel -->
    <!-- that has been registered in the system -->
    <channel>Campus Status Announcements</channel>


    <!-- this is the name of the producing system -->
    <!-- the value must match a registered producer -->
    <producer>Campus Announcements System</producer>

    <!-- these are the people that the message is sent on -->
    <!-- behalf of -->
    <senders>
        <sender>John Fereira</sender>
    </senders>


    <!-- who is the notification going to? -->
    <recipients>
        <group>Everyone</group>
        <user>jaf30</user>
    </recipients>


    <!--  fyi or acknowledge -->
    <deliveryType>fyi</deliveryType>


    <!-- optional date and time that a notification should be sent -->
    <!-- use this for scheduling a single future notification to happen -->
    <sendDateTime>2006-01-01T00:00:00</sendDateTime>


    <!-- optional date and time that a notification should be removed -->
    <!-- from all recipients' lists, b/c the message no longer applies -->
    <autoRemoveDateTime>3000-01-01T00:00:00</autoRemoveDateTime>


    <!-- this is the name of the priority of the message -->
    <!-- priorities are registered in the system, so your value -->
    <!-- here must match one of the registered priorities -->
    <priority>Normal</priority>


    <title>School is Closed</title>


    <!-- this is the name of the content type for the message -->
    <!-- content types are registered in the system, so your value -->
    <!-- here must match one of the registered contents -->
    <contentType>Simple</contentType>


    <!-- actual content of the message -->
    <content xmlns="ns:notification/ContentTypeSimple"
        xsi:schemaLocation="ns:notification/ContentTypeSimple
        resource:notification/ContentTypeSimple">
		
        <message>Snow Day! School is closed.</message>
    </content>
</notification>

<?xml version="1.0" encoding="UTF-8"?>


<notification xmlns="ns:notification/NotificationMessage"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="ns:notification/NotificationMessage
    resource:notification/NotificationMessage">
    <!-- this is the name of the notification channel -->
    <!-- that has been registered in the system -->
    <channel>Concerts Coming to Campus</channel>


    <!-- this is the name of the producing system -->
    <!-- the value must match a registered producer -->
    <producer>Campus Events Office</producer>


    <!-- these are the people that the message is sent on -->
    <!-- behalf of -->
    <senders>
        <sender>ag266</sender>
        <sender>jaf30</sender>
    </senders>


    <!-- who is the notification going to? -->
        <recipients>
            <group>Group X</group>
            <group>Group Z</group>
            <user>ag266</user>
            <user>jaf30</user>
            <user>arh14</user>
        </recipients>


    <!--  fyi or acknowledge -->
    <deliveryType>fyi</deliveryType>


    <!-- optional date and time that a notification should be sent -->
    <!-- use this for scheduling a single future notification to happen -->
    <sendDateTime>2006-01-01 00:00:00.0</sendDateTime>


    <!-- optional date and time that a notification should be removed -->
    <!-- from all recipients' lists, b/c the message no longer applies -->
    <autoRemoveDateTime>2007-01-01 00:00:00.0</autoRemoveDateTime>


    <!-- this is the name of the priority of the message -->
    <!-- priorities are registered in the system, so your value -->
    <!-- here must match one of the registered priorities -->
    <priority>Normal</priority>


    <!-- this is the name of the content type for the message -->
    <!-- content types are registered in the system, so your value -->
    <!-- here must match one of the registered contents -->
    <contentType>Event</contentType>


    <!-- actual content of the message -->
    <content>
        <message>CCC presents The Strokes at Cornell</message>

        
        <!-- an event that it happening on campus -->
        <event xmlns="ns:notification/ContentEvent" 
            xsi:schemaLocation="ns:notification/ContentEvent
            resource:notification/ContentEvent">
            <summary>CCC presents The Strokes at Cornell</summary>
            <description>blah blah blah</description>
            <location>Barton Hall</location>
            <startDateTime>2006-01-01T00:00:00</startDateTime>
            <stopDateTime>2007-01-01T00:00:00</stopDateTime>
        </event>
    </content>
</notification>

First, create a String that includes the XML content for the notification, as described in the Notification Message document of the TRG for KEN. In the following example code, the XML representation of the notification is read as a file from the file system in the main method, and the code calls the MySendNotification method to invoke the Notification web service.

A SOAP style web services binding stub is available in the notification.jar file, as described above in the Dependencies section.

You may use this code as a template for sending a notification using the web service:

package edu.cornell.library.notification;


import org.apache.commons.io.IOUtils;
import org.kuali.notification.client.ws.stubs.NotificationWebServiceSoapBindingStub;


import java.io.IOException;

import java.io.InputStream;
import java.net.URL;


public class MyNotificationWebServiceClient   {
  private final  static String WEB_SERVICE_URL = "http://localhost:8080/notification/services/Notification";

  public static void MySendNotification(String notificationMessageAsXml) throws Exception {
    URL url = new URL(WEB_SERVICE_URL);
    NotificationWebServiceSoapBindingStub stub = new NotificationWebServiceSoapBindingStub(url, null);
    String responseAsXml = stub.sendNotification(notificationMessageAsXml);
    // do something useful with the response
    System.out.println(responseAsXml);
  }

  public static void main(String[] args) {
    InputStream notificationXML = MyNotificationWebServiceClient.class.getResourceAsStream("webservice_notification.xml");
    String notificationMessageAsXml = "";
    try {
      notificationMessageAsXml = IOUtils.toString(notificationXML);
    } catch (IOException ioe) {
      throw new RuntimeException("Error loading webservice_notification.xml");
    }

    try {
      MySendNotification(notificationMessageAsXml);
    } catch (Exception ioe) {
      throw new RuntimeException("Error running webservice");
    }
  }

}

Begin to build a Kuali Enterprise Workflow the same as you build any other Java-enabled web application. You build it with all the business logic for the application and, for example, communication to the workflow engine using web services.

As an example, the Travel Request Client Web Application uses Struts, Spring, and OJB.

For the rest of this section, this guide refers to the Java application communicating with the Kuali Enterprise Workflow as the Client Application. The Client Application needs a service that will interact with the workflow system. This service will perform actions such as locating a document in the workflow system and routing the document.

Below are examples from the Travel Request Sample Client. The methods in the TravelDocumentService class find a TravelDocument in the workflow system, save and route a TravelDocument, and validate a TravelDocument.

findByDocHeaderId() - Finds a Document in the workflow engine:

public TravelDocument findByDocHeaderId(Long docHeaderId, String principalId) {
    if (docHeaderId == null) {
        throw new IllegalArgumentException("invalid (null) docHeaderId");
    }
    TravelDocument result = travelDocumentDao.findByDocHeaderId(docHeaderId);
    if (result != null) {
        // convert DocAccountJoins into FinancialAccounts
        ArrayList accounts = new ArrayList();
        for (Iterator joins = result.getDocAccountJoins().iterator(); joins.hasNext();) {
            DocumentAccountJoin join = (DocumentAccountJoin) joins.next();

            FinancialAccount account = financialAccountService.findByAccountNumber(join.getAccountNumber());

            accounts.add(account);
        }
        result.setFinancialAccounts(accounts);
        try {
            WorkflowDocument document = new WorkflowDocument( principalId, result.getDocHeaderId());
        } catch (WorkflowException e) {
            LOG.error("caught WorkflowException: ", e);
            throw new RuntimeException(e);
        }
    }
    return result;
}                

The TravelDocumentServiceImpl class populates the attribute values on the workflow document (Employee, Account) that will be used for future routing. It does this by calling its getEmployeeAttribute() and getAccountAttribute() methods and adding the results to the workflow document by calling the addAttributeDefinition() method.

private WorkflowAttributeDefinitionVO getEmployeeAttribute(TravelDocument travelDocument) {
    WorkflowAttributeDefinitionDTO attrDef = new WorkflowAttributeDefinitionDTO("edu.sampleu.travel.workflow.EmployeeAttribute");
    String principalName = travelDocument.getTravelerUsername();
    attrDef.addConstructorParameter(principalName);
    return attrDef;
}



private List getAccountAttributes(TravelDocument travelDocument) {
    List accounts = travelDocument.getFinancialAccounts();
    List accountAttributes = new ArrayList();
    for (Iterator accountIterator = accounts.iterator(); accountIterator.hasNext();) {
        WorkflowAttributeDefinitionDTO attrDef = new WorkflowAttributeDefinitionDTO("edu.sampleu.travel.workflow.AccountAttribute");
        FinancialAccount account = (FinancialAccount)accountIterator.next();
        attrDef.addConstructorParameter(account.getAccountNumber());
        accountAttributes.add(attrDef);
    }
    return accountAttributes;
}

In the Travel Request Sample Client, the WorkflowDocHandlerAction struts action class calls the workflow lifecycle methods (approve, acknowledge, etc.) on the workflow document.

WorkflowDocHandlerAction - Take approve action. (Each workflow action - acknowledge, complete, etc. - is like this):

public ActionForward approve(ActionMapping mapping, ActionForm form, HttpServletRequest request, HttpServletResponse response) throws Exception {
    LOG.info("entering approve() method ...");
    DocHandlerForm docHandlerForm = (DocHandlerForm) form;
    WorkflowDocument document = docHandlerForm.getWorkflowDocument()
 document.approve(docHandlerForm.getAnnotation());
    saveDocumentActionMessage("general.routing.approved", request);
    LOG.info("forwarding to actionTaken from approve()");
    return mapping.findForward("actionTaken");

}

Set up the WorkflowDocument in the initializeBaseFormState() method of the DispatchActionBase from which the Struts action classes inherit. Obtain the workflow document with this line of code:

String principalId = getUserSession(request).getPrincipalId();
WorkflowDocument document = new WorkflowDocument(principalId, docId);

Package the Client Application (client web application) for deployment the way you normally package web applications. The Travel Request Sample Web Application does this with an Ant build script. The dist step of the build.xml script builds the SampleWorkflowClient.war file.

Deploy the plugin to your workflow installation. Copy the plugin directory structure to your application plugins directory. Please see the Workflow Plugin Guide for more information.

Deploy the Client Web Application to your Application server the way you normally deploy web applications.

To effectively use any of the KEW integration modes besides bundled, a Standalone Rice Server will need to be deployed.

Here is a diagram illustrating what a sample embedded deployment might look look.

Figure 3.1. Sample KEW embedded deployment

Bundled mode is the same as embedded mode except that the client application embeds the entire Kuali Rice system within it (including the web application). The embedding of the web application portion is accomplished by utilizing Struts Modules.

Configuration is the same as embedded mode, with the exception of loading the web application portions in the web.xml:

<filter>
    <filter-name>UserLoginFilter</filter-name>
    <filter-class>org.kuali.rice.kew.web.UserLoginFilter</filter-class>

</filter>


<filter-mapping>
    <filter-name>UserLoginFilter</filter-name>
    <servlet-name>action</servlet-name>
</filter-mapping>



<servlet>
    <servlet-name>action</servlet-name>
    <servlet-class>org.apache.struts.action.ActionServlet</servlet-class>
    .. other struts configuration if applicable
    <init-param>
        <param-name>config/en</param-name>
        <param-value>/en/WEB-INF/struts-config.xml</param-value>
    </init-param>
    <load-on-startup>0</load-on-startup>
</servlet>


<servlet>
    <servlet-name>remoting</servlet-name>
    <servlet-class>org.kuali.rice.ksb.messaging.servlet.KSBDispatcherServlet</servlet-class>
    <load-on-startup>1</load-on-startup>
</servlet>



<servlet>
    <servlet-name>export</servlet-name>
    <servlet-class>org.kuali.rice.kew.export.web.ExportServlet</servlet-class>
</servlet>


<servlet>
    <servlet-name>attachment</servlet-name>
    <servlet-class>org.kuali.rice.kew.notes.web.AttachmentServlet</servlet-class>
</servlet>



<servlet>
    <servlet-name>edoclite</servlet-name>
    <servlet-class>org.kuali.rice.kew.edl.EDLServlet</servlet-class>
</servlet>



<servlet-mapping>
    <servlet-name>remoting</servlet-name>
    <url-pattern>/remoting/*</url-pattern>
</servlet-mapping>


<servlet-mapping>
    <servlet-name>action</servlet-name>
    <url-pattern>*.do</url-pattern>
</servlet-mapping>

<servlet-mapping>


    <servlet-name>export</servlet-name>
    <url-pattern>/export/*</url-pattern>
</servlet-mapping>


<servlet-mapping>
  
    <servlet-name>attachment</servlet-name>
    <url-pattern>/en/attachment/*</url-pattern>
</servlet-mapping>


<servlet-mapping>
    <servlet-name>edoclite</servlet-name>
    <url-pattern>/en/EDocLite</url-pattern>
</servlet-mapping>

org.kuali.rice.kew.web.UserLoginFilter – This filter is used to assist the KEW bundled web application in determining who the authenticated user is. Specifically, the login filter invokes the KIM identity management service to determine the identity of the authenticated user.

Typically, a previously executed filter will challenge the user on entry to a Rice web page for their authentication credentials using CAS or some other form of single sign on (SSO) authentication system.

For development and testing purposes, Rice provides a simple filter implementation that will present a simple sign on screen. This screen displays only a single login entry field and submit button. The user can enter their username (no password) and press the submit button, and the system authenticates the user for entry into the system.

This can be configured as follows in the web.xml:

<filter>
    <filter-name>LoginFilter</filter-name>
    <filter-class>org.kuali.rice.kew.web.UserLoginFilter</filter-class>

</filter>



<filter-mapping>
    <filter-name>LoginFilter</filter-name>
    <servlet-name>action</servlet-name>
</filter-mapping>

and in the rice-config.xml:

<param name="filter.login.class">org.kuali.rice.kew.web.DummyLoginFilter</param>
<param name="filtermapping.login.1">/*</param>

org.apache.struts.action.ActionServlet - The Struts servlet which loads the KEW Struts module. The module name should be 'en'. Struts only allows a single Action Servlet so if you are using Struts in your application, all of your Struts modules will need to be configured using the init-param elements in this servlet definition.

org.kuali.rice.ksb.messaging.servlet.KSBDispatcherServlet - A servlet which dispatches http requests for the Kuali Service Bus (see KSB documentation for more details). The servlet mapping here should correspond to the serviceServletUrl configuration parameter for the KSBConfigurer.

org.kuali.rice.kew.export.web.ExportServlet - serves exports of lookup results as XML files

org.kuali.rice.kew.notes.web.AttachmentServlet - serves attachments that have been attached to documents using the KEW Notes and Attachments framework

org.kuali.rice.kew.edl.EDLServlet - The servlet used to interact with eDocLite documents. See eDocLite documentation for more information.

Here is the Spring configuration for a thin client in ThinClientSpring.xml:

<!DOCTYPE beans PUBLIC "-//SPRING//DTD BEAN//EN" "http://www.springframework.org/dtd/spring-beans.dtd">

<beans>
    <!-- point Rice to the file containing your configuration params -->
    <bean id="config" class="org.kuali.rice.core.config.spring.ConfigFactoryBean">
        <property name="configLocations">
            <list>
                <value>classpath: yourThinClientApp-config.xml</value>
            </list>
        </property>
    </bean>
    <!-- Pull your configuration params out as Properties -->
    <bean id="configProperties" 
class="org.springframework.beans.factory.config.MethodInvokingFactoryBean">
        <property name="targetObject" ref="config" />
        <property name="targetMethod" value="getProperties" />
    </bean>
    <!-- expose configuration params to Spring -->
    <bean class=
"org.springframework.beans.factory.config.PropertyPlaceholderConfigurer">
        <property name="properties" ref="configProperties" />
    </bean>
    <!-- The RiceConfigurer that sets up thin client mode -->
    <bean id="rice" class="org.kuali.rice.kew.config.ThinClientKEWConfigurer">
        <!-- inject the "config" bean into our configurer -->
        <property name="rootConfig" ref="config" />
    </bean>
</beans>  

Since KEW and KIM use the KSB to expose their services, the endpoint URLs are the same as those exported by the KSB.

An example configuration for these might be:

<param name=
"workflowdocument.javaservice.endpoint">http://yourlocalip/kr-dev/remoting/WorkflowDocumentActionsService</param>
<param name=
"workflowutility.javaservice.endpoint">http://yourlocalip/kr-dev/remoting/WorkflowUtilityService</param>
<param name=
"identity.javaservice.endpoint">http://yourlocalip/kr-dev/remoting/kimIdentityService</param>
<param name=
"group.javaservice.endpoint">http://yourlocalip/kr-dev/remoting/kimGroupService</param>

Here is a diagram showing what a thin client deployment might look like.

Figure 3.3. Thin client deployment diagram

If embedded.server parameter is enabled (set to true), then two additional features will be loaded when KEW is started:

The XML Loader will poll a directory for XML files to ingest into the system (as configured by the data.xml.* properties).

The Email Reminders will handle sending Daily and Weekly batch emails for users that have their preferences set accordingly.

KEW requires and uses the database platform implementation in order to function. These may be be implemented differently for each support database management system.

The current functional implementations of this platform are:

When running a Standalone Rice Server, you may want to implement your own filters for authentication purposes. The system comes with a special filter that will read filter definitions and mappings from the configuration system.

The Bootstrap Filter is a generic filter that is applied to all web requests, which then delegates to any filters and are setup through the default configuration. This mechanism allows registration of institution-specific filters without the necessity of modifying the web application configuration file (/WEB-INF/web.xml) within the standalone webapp.

Filter syntax is as follows:

<param name="filter.filter name.class">class name of filter</param>

filter name is an arbitrary name for your filter:

<param name="filter.myfilter.class">edu.institution.organization.MyFilter</param>

Any number of configuration parameters may be defined for a given filter as follows:

<param name="filter.filter name.filter param name">filter param value</param>

For example:

<param name="filter.myfilter.color">red</param>

<param name="filter.myfilter.shape">square</param>

For custom filters to be invoked, they must first be mapped to requests. That is done via the filter mapping parameter:

<param name="filtermapping.filter name.optional order index">path matching expression</param>

filter name is the name of your previously defined filter, optional order index is an optional integer used to specify the position of the filter in the invocation order, and path matching expression is a Servlet-specification-compatible url pattern.

<param name="filtermapping.myfilter.1">/special/path/</param>

If an order index is not specified, it is assumed to be 0. Filters with equivalent order are ordered arbitrarily with relation to each other (not in order of filter or mapping definition). A full example follows:

<param name="filter.myfilter.class">edu.institution.organization.MyFilter</param>

<param name="filter.myfilter.color">red</param>

<param name="filter.myfilter.shape">square</param>
<param name="filter.securityfilter.class">edu.institution.organization.SecurityFilter</param>

<param name="filter.securityfilter.secretKey">abracadabra</param>

<param name="filter.compressionfilter.class">edu.institution.organization.CompressionFilter</param>
<param name="filter.compressionfilter.compressLevel">5</param>
<param name="filtermapping.securityfilter.1">/secure/</param>

<param name="filtermapping.myfilter.2">/special/path/</param>

<param name="filtermapping.compressionfilter.3">/*</param>

Because the operation of parts of KEW is dependent on a set of Document Types and Attributes being available within the system, there is some bootstrap XML that you will want to import. The easiest way to do this is to import the files in the following locations using the XML Ingester:

These files include the following:

Application constants you may want to change:

In the core document types and rules config, you will need to change:

To upload XML, go to Ingester UI and select the XML file that you want to import:

Figure 3.5. Ingester

After upload, notice the red arrow and the statement, Ingested xml doc: <name of file>:

Figure 3.6. Ingestion Complete

The main Route Queue screen:

Figure 3.7. Route Queue Screen

Examining this sample screen, we see there are five entries in the route queue, one on each row. The columns display information about each entry:

Once a queue entry has been successfully processed, it is deleted from the queue.

In the screen shot above, we see two entries with special Processors. One of these special Processors is sending daily email reminders. The other one is sending weekly email reminders. When these entries are picked up from the queue, they do their work and then queue themselves back up for a day (or a week) later. Therefore, these entries never really leave the queue.

Of the other three entries, we can see that two have a status of ROUTING while one has a status of QUEUED. What this means is that, at the instant that this screen shot was taken, the two that are ROUTING have been picked up by the route manager and are being processed. The one that is QUEUED will be picked up the next time that the route manager checks the queue.

Sometimes it is necessary to manually edit a route queue entry that is halted inside of the queue. This situation might happen when:

In all cases, the status of the entry is ROUTING, but there is no longer a worker thread processing the entry. Currently, KEW doesn't implement any auto-detection of failure cases. To put one of these entries in a state where it can be picked up by the route manager again, simply click the Edit link and set the entry’s status back to QUEUED. Here's a screen shot of the Route Queue Entry - Edit screen:

Figure 3.8. Route Queue Entry Edit Screen

Use the Queue Status dropdown list to change the status of the entry. You may also want to set the Retry Count to zero to allow you to diagnose the problem before the document goes into exception routing.

BlanketApproveTest

<documentType>
    <name>BlanketApproveTest</name>
    <description>BlanketApproveTest</description>
    <label>BlanketApproveTest</label>
    <postProcessorName>org.kuali.rice.kew.postprocessor.DefaultPostProcessor</postProcessorName>
    <superUserGroupName namespace=”KR-WKFLW” >TestWorkgroup</superUserGroupName>
    <blanketApproveGroupName namespace=”KR-WKFLW”>TestWorkgroup</blanketApproveGroupName>
    <defaultExceptionGroupName namespace=”KR-WKFLW”> TestWorkgroup</defaultExceptionGroupName>
    <docHandler>_blank</docHandler>
    <active>true</active>
    <policies>
        <policy>
            <name>DEFAULT_APPROVE</name>
            <value>false</value>
        </policy>
    </policies>

</documentType> 

BlanketApproveSequentialTest

<documentType>
    <name>BlanketApproveSequentialTest</name>
    <parent>BlanketApproveTest</parent>
    <description>BlanketApproveSequentialTest</description>
    <label>BlanketApproveSequentialTest</label>
    <postProcessorName>org.kuali.rice.kew.postprocessor.DefaultPostProcessor</postProcessorName>
    <superUserGroupName namespace=”KR-WKFLW”>WorkflowAdmin</superUserGroupName>
    <blanketApproveGroupName namespace=”KR-WKFLW”>TestWorkgroup</blanketApproveGroupName>
    <defaultExceptionGroupName namespace=”KR-WKFLW”>WorkflowAdmin</defaultExceptionGroupName>

    <docHandler>_blank</docHandler>
    <active>true</active>
    <routePaths>
        <routePath>
            <start name="AdHoc" nextNode="WorkflowDocument" />
            <requests name="WorkflowDocument" nextNode="WorkflowDocument2" />
            <requests name="WorkflowDocument2" nextNode="Acknowledge1" />
            <requests name="Acknowledge1" nextNode="Acknowledge2" />
            <requests name="Acknowledge2" />
        </routePath>
    </routePaths>
    <routeNodes>
        <start name="AdHoc">
            <activationType>P</activationType>
        </start>
        <requests name="WorkflowDocument">
            <activationType>P</activationType>
            <ruleTemplate>WorkflowDocumentTemplate</ruleTemplate>
        </requests>
        <requests name="WorkflowDocument2">
            <activationType>P</activationType>
            <ruleTemplate>WorkflowDocument2Template</ruleTemplate>
        </requests>
        <requests name="Acknowledge1">
            <activationType>P</activationType>
            <ruleTemplate>Ack1Template</ruleTemplate>
        </requests>
        <requests name="Acknowledge2">
            <activationType>P</activationType>
            <ruleTemplate>Ack2Template</ruleTemplate>
        </requests>
    </routeNodes>
</documentType> 

Figure 3.9. BlanketApproveSequentialTest Workflow

BlanketApproveParallelTest

<documentType>
    <name>BlanketApproveParallelTest</name>
    <parent>BlanketApproveTest</parent>
    <description>BlanketApproveParallelTest</description>
    <label>BlanketApproveParallelTest</label>
    <postProcessorName>org.kuali.rice.kew.postprocessor.DefaultPostProcessor</postProcessorName>
    <superUserGroupName namespace=”KR-WKFLW” >TestWorkgroup</superUserGroupName>
    <blanketApproveGroupName namespace=”KR-WKFLW”>TestWorkgroup</blanketApproveGroupName>
    <defaultExceptionGroupName namespace=”KR-WKFLW”> TestWorkgroup</defaultExceptionGroupName>
    <docHandler>_blank</docHandler>
    <active>true</active>
    <routePaths>
        <routePath>
            <start name="AdHoc" nextNode="WorkflowDocument" />
            <requests name="WorkflowDocument" nextNode="Split" />
            <split name="Split" nextNode="WorkflowDocumentFinal">
                <branch name="B1">
                    <requests name="WorkflowDocument2-B1" nextNode="WorkflowDocument3-B1" />
                    <requests name="WorkflowDocument3-B1" nextNode="Join" />
                </branch>
                <branch name="B2">
                    <requests name="WorkflowDocument3-B2" nextNode="WorkflowDocument2-B2" />
                    <requests name="WorkflowDocument2-B2" nextNode="Join" />
                </branch>
                <branch name="B3">
                    <requests name="WorkflowDocument4-B3" nextNode="Join" />
                </branch>
                <join name="Join" />
            </split>
            <requests name="WorkflowDocumentFinal" nextNode="Acknowledge1" />
            <requests name="Acknowledge1" nextNode="Acknowledge2" />
            <requests name="Acknowledge2" />
        </routePath>
    </routePaths>
    <routeNodes>
        <start name="AdHoc">
            <activationType>P</activationType>
        </start>
        <requests name="WorkflowDocument">
            <activationType>P</activationType>
            <ruleTemplate>WorkflowDocumentTemplate</ruleTemplate>
        </requests>
        <split name="Split" />
        <requests name="WorkflowDocument2-B1">
            <activationType>P</activationType>
            <ruleTemplate>WorkflowDocument2Template</ruleTemplate>
        </requests>
        <requests name="WorkflowDocument2-B2">
            <activationType>P</activationType>
            <ruleTemplate>WorkflowDocument2Template</ruleTemplate>
        </requests>
        <requests name="WorkflowDocument3-B1">
            <activationType>P</activationType>
            <ruleTemplate>WorkflowDocument3Template</ruleTemplate>
        </requests>
        <requests name="WorkflowDocument3-B2">
            <activationType>P</activationType>
            <ruleTemplate>WorkflowDocument3Template</ruleTemplate>
        </requests>
        <requests name="WorkflowDocument4-B3">
            <activationType>P</activationType>
            <ruleTemplate>WorkflowDocument4Template</ruleTemplate>
        </requests>
        <join name="Join" />
        <requests name="WorkflowDocumentFinal">
            <activationType>P</activationType>
            <ruleTemplate>WorkflowDocumentFinalTemplate</ruleTemplate>
        </requests>
        <requests name="Acknowledge1">
            <activationType>P</activationType>
            <ruleTemplate>Ack1Template</ruleTemplate>
        </requests>
        <requests name="Acknowledge2">
            <activationType>P</activationType>
            <ruleTemplate>Ack2Template</ruleTemplate>
        </requests>
    </routeNodes>
</documentType> 

Figure 3.10. BlanketApproveParallelTest Workflow

NotificationTest

<documentType>
    <name>NotificationTest</name>
    <description>NotificationTest</description>
    <label>NotificationTest</label>
    <postProcessorName>org.kuali.rice.kew.postprocessor.DefaultPostProcessor</postProcessorName>
    <superUserGroupName namespace=”KR-WKFLW” >TestWorkgroup</superUserGroupName>
    <blanketApproveGroupName namespace=”KR-WKFLW”>TestWorkgroup</blanketApproveGroupName>
    <defaultExceptionGroupName namespace=”KR-WKFLW”> TestWorkgroup</defaultExceptionGroupName>
    <docHandler>_blank</docHandler>
    <active>true</active>
    <routePaths>
        <routePath>
            <start name="AdHoc" nextNode="NotifyFirst" />
            <requests name="NotifyFirst" nextNode="Split" />
            <split name="Split" nextNode="NotifyFinal">
                <branch name="LeftBranch">
                    <requests name="NotifyLeftBranch" nextNode="Join" />
                </branch>
                <branch name="RightBranch">
                    <requests name="NotifyRightBranch" nextNode="Join" />
                </branch>
                <join name="Join" />
            </split>
            <requests name="NotifyFinal" />
        </routePath>
    </routePaths>
    <routeNodes>
        <start name="AdHoc">
            <activationType>P</activationType>
        </start>
        <requests name="NotifyFirst">
            <activationType>P</activationType>
            <ruleTemplate>NotifyFirstTemplate</ruleTemplate>
        </requests>
        <split name="Split" />
        <requests name="NotifyLeftBranch">
            <activationType>P</activationType>
            <ruleTemplate>NotifyLeftBranchTemplate</ruleTemplate>
        </requests>
        <requests name="NotifyRightBranch">
            <activationType>P</activationType>
            <ruleTemplate>NotifyRightBranchTemplate</ruleTemplate>
        </requests>
        <join name="Join" />
        <requests name="NotifyFinal">
            <activationType>P</activationType>
            <ruleTemplate>NotifyFinalTemplate</ruleTemplate>
        </requests>
    </routeNodes>
</documentType> 

Figure 3.11. NotificationTest Workflow

NotificationTestChild

<documentType>
    <name>NotificationTestChild</name>
    <parent>NotificationTest</parent>
    <description>NotificationTest</description>
    <label>NotificationTest</label>
    <postProcessorName>org.kuali.rice.kew.postprocessor.DefaultPostProcessor</postProcessorName>
    <superUserGroupName namespace=”KR-WKFLW” >TestWorkgroup</superUserGroupName>
    <blanketApproveGroupName namespace=”KR-WKFLW”>TestWorkgroup</blanketApproveGroupName>
    <defaultExceptionGroupName namespace=”KR-WKFLW”> TestWorkgroup</defaultExceptionGroupName>
    <docHandler>_blank</docHandler>
    <active>true</active>
    <policies>
        <policy>
            <name>SEND_NOTIFICATION_ON_SU_APPROVE</name>
            <value>true</value>
        </policy>
    </policies>
</documentType>

BlanketApproveMandatoryNodeTest

<documentType>
    <name>BlanketApproveMandatoryNodeTest</name>
    <parent>BlanketApproveTest</parent>
    <description>BlanketApproveMandatoryNodeTest</description>
    <label>BlanketApproveMandatoryNodeTest</label>
    <postProcessorName>org.kuali.rice.kew.postprocessor.DefaultPostProcessor</postProcessorName>
    <superUserGroupName namespace=”KR-WKFLW” >TestWorkgroup</superUserGroupName>
    <blanketApproveGroupName namespace=”KR-WKFLW”>TestWorkgroup</blanketApproveGroupName>
    <defaultExceptionGroupName namespace=”KR-WKFLW”> TestWorkgroup</defaultExceptionGroupName>
    <docHandler>_blank</docHandler>
    <active>true</active>
    <routePaths>
        <routePath>
            <start name="AdHoc" nextNode="WorkflowDocument" />
            <requests name="WorkflowDocument" nextNode="WorkflowDocument2" />
            <requests name="WorkflowDocument2" nextNode="Acknowledge1" />
            <requests name="Acknowledge1" nextNode="Acknowledge2" />
            <requests name="Acknowledge2" />
        </routePath>
    </routePaths>
    <routeNodes>
        <start name="AdHoc">
            <activationType>P</activationType>
        </start>
        <requests name="WorkflowDocument">
            <activationType>P</activationType>
            <ruleTemplate>WorkflowDocumentTemplate</ruleTemplate>
            <mandatoryRoute>true</mandatoryRoute>
        </requests>
        <requests name="WorkflowDocument2">
            <activationType>P</activationType>
            <ruleTemplate>WorkflowDocument2Template</ruleTemplate>
            <mandatoryRoute>true</mandatoryRoute>
            <finalApproval>true</finalApproval>
        </requests>
        <requests name="Acknowledge1">
            <activationType>P</activationType>
            <ruleTemplate>Ack1Template</ruleTemplate>
        </requests>
        <requests name="Acknowledge2">
            <activationType>P</activationType>
            <ruleTemplate>Ack2Template</ruleTemplate>
        </requests>
    </routeNodes>
</documentType> 

Figure 3.12. Blankte Approve Mandatory Test

SaveActionEventTest

<documentType>
    <name>SaveActionEventTest</name>
    <description>SaveActionEventTest</description>
    <label>SaveActionEventTest</label>		<postProcessorName>org.kuali.rice.kew.postprocessor.DefaultPostProcessor</postProcessorName>
    <superUserGroupName namespace=”KR-WKFLW” >TestWorkgroup</superUserGroupName>
    <blanketApproveGroupName namespace=”KR-WKFLW”>TestWorkgroup</blanketApproveGroupName>
    <defaultExceptionGroupName namespace=”KR-WKFLW”> TestWorkgroup</defaultExceptionGroupName>
    <docHandler>_blank</docHandler>
    <active>true</active>
    <policies>
        <policy>
            <name>DEFAULT_APPROVE</name>
            <value>false</value>
        </policy>
    </policies>
    <routePaths>
        <routePath>
            <start name="AdHoc" nextNode="WorkflowDocument" />
            <requests name="WorkflowDocument" />
        </routePath>
    </routePaths>
    <routeNodes>
        <start name="AdHoc">
            <activationType>P</activationType>
        </start>
        <requests name="WorkflowDocument">
            <activationType>P</activationType>
            <ruleTemplate>WorkflowDocumentTemplate</ruleTemplate>
        </requests>
    </routeNodes>
</documentType> 

Figure 3.13. Save Action Event Test

SaveActionEventTestNonInitiator

<documentType>
    <name>SaveActionEventTestNonInitiator</name>
    <description>SaveActionEventTest With No Initiator Only Save Required</description>
    <label>SaveActionEventTestNonInitiator</label>
    <postProcessorName>org.kuali.rice.kew.postprocessor.DefaultPostProcessor</postProcessorName>
    <superUserGroupName namespace=”KR-WKFLW” >TestWorkgroup</superUserGroupName>
    <blanketApproveGroupName namespace=”KR-WKFLW”>TestWorkgroup</blanketApproveGroupName>
    <defaultExceptionGroupName namespace=”KR-WKFLW”> TestWorkgroup</defaultExceptionGroupName>
    <docHandler>_blank</docHandler>
    <active>true</active>
    <policies>
        <policy>
            <name>DEFAULT_APPROVE</name>
            <value>false</value>
        </policy>
        <policy>
            <name>INITIATOR_MUST_SAVE</name>
            <value>false</value>
        </policy>
    </policies>
    <routePaths>
        <routePath>
            <start name="AdHoc" nextNode="WorkflowDocument" />
            <requests name="WorkflowDocument" />
        </routePath>
    </routePaths>
    <routeNodes>
        <start name="AdHoc">
            <activationType>P</activationType>
        </start>
        <requests name="WorkflowDocument">
            <activationType>P</activationType>
            <ruleTemplate>WorkflowDocumentTemplate</ruleTemplate>
        </requests>
    </routeNodes>
</documentType>

Figure 3.14. Save Action Even Test: Non-Initiator

TakeWorkgroupAuthorityDoc

<documentType>
    <name>TakeWorkgroupAuthorityDoc</name>
    <description>TakeWorkgroupAuthority Action Test</description>
    <label>TakeWorkgroupAuthorityDoc</label>
    <postProcessorName>org.kuali.rice.kew.postprocessor.DefaultPostProcessor</postProcessorName>
    <superUserGroupName namespace=”KR-WKFLW” >TestWorkgroup</superUserGroupName>
    <blanketApproveGroupName namespace=”KR-WKFLW”>TestWorkgroup</blanketApproveGroupName>
    <defaultExceptionGroupName namespace=”KR-WKFLW”> TestWorkgroup</defaultExceptionGroupName>
    <docHandler>_blank</docHandler>
    <active>true</active>
    <policies>
        <policy>
            <name>DEFAULT_APPROVE</name>
            <value>false</value>
        </policy>
    </policies>
    <routePaths>
        <routePath>
            <start name="AdHoc" nextNode="WorkgroupByDocument" />
            <requests name="WorkgroupByDocument" />
        </routePath>
    </routePaths>
    <routeNodes>
        <start name="AdHoc">
            <activationType>P</activationType>
        </start>
        <requests name="WorkgroupByDocument">
            <activationType>P</activationType>
            <ruleTemplate>WorkgroupByDocument</ruleTemplate>
        </requests>
    </routeNodes>
</documentType> 

Figure 3.15. Take Workgroup Authority

MoveSequentialTest

<documentType>
    <name>MoveSequentialTest</name>
    <parent>BlanketApproveTest</parent>
    <description>Move Sequential Test</description>
    <label>Move Sequential Test</label>

    <postProcessorName>org.kuali.rice.kew.postprocessor.DefaultPostProcessor</postProcessorName>
    <superUserGroupName namespace=”KR-WKFLW” >TestWorkgroup</superUserGroupName>
    <blanketApproveGroupName namespace=”KR-WKFLW”>TestWorkgroup</blanketApproveGroupName>
    <defaultExceptionGroupName namespace=”KR-WKFLW”> TestWorkgroup</defaultExceptionGroupName>
    <docHandler>_blank</docHandler>
    <active>true</active>
    <routePaths>
        <routePath>
            <start name="AdHoc" nextNode="WorkflowDocument" />
            <requests name="WorkflowDocument" nextNode="WorkflowDocument2" />
            <requests name="WorkflowDocument2" nextNode="Acknowledge1" />
            <requests name="Acknowledge1" nextNode="Acknowledge2" />
            <requests name="Acknowledge2" />
        </routePath>
    </routePaths>
    <routeNodes>
        <start name="AdHoc">
            <activationType>P</activationType>
        </start>
        <requests name="WorkflowDocument">
            <activationType>P</activationType>
            <ruleTemplate>WorkflowDocumentTemplate</ruleTemplate>
        </requests>
        <requests name="WorkflowDocument2">
            <activationType>P</activationType>
            <ruleTemplate>WorkflowDocument2Template</ruleTemplate>
        </requests>
        <requests name="Acknowledge1">
            <activationType>P</activationType>
            <ruleTemplate>Ack1Template</ruleTemplate>
        </requests>
        <requests name="Acknowledge2">
            <activationType>P</activationType>
            <ruleTemplate>Ack2Template</ruleTemplate>
        </requests>
    </routeNodes>
</documentType>

Figure 3.16. Move Sequential Test

MoveInProcessTest

<documentType>
    <name>MoveInProcessTest</name>
    <parent>BlanketApproveTest</parent>
    <description>Move In Process Test</description>
    <label>Move In Process Test</label>
    <postProcessorName>org.kuali.rice.kew.postprocessor.DefaultPostProcessor</postProcessorName>
    <superUserGroupName namespace=”KR-WKFLW” >TestWorkgroup</superUserGroupName>
    <blanketApproveGroupName namespace=”KR-WKFLW”>TestWorkgroup</blanketApproveGroupName>
    <defaultExceptionGroupName namespace=”KR-WKFLW”> TestWorkgroup</defaultExceptionGroupName>
    <docHandler>_blank</docHandler>
    <active>true</active>
    <routePaths>
        <routePath>
            <start name="AdHoc" nextNode="WorkflowDocument" />
            <requests name="WorkflowDocument" nextNode="MyRadSubProcess" />
            <process name="MyRadSubProcess" nextNode="WorkflowDocumentFinal" />
            <requests name="WorkflowDocumentFinal" />
        </routePath>
        <routePath processName="MyRadSubProcess" initialNode="WorkflowDocument2">
            <requests name="WorkflowDocument2" nextNode="WorkflowDocument3" />
            <requests name="WorkflowDocument3" />
        </routePath>
    </routePaths>
    <routeNodes>
        <start name="AdHoc">
            <activationType>P</activationType>
        </start>
        <requests name="WorkflowDocument">
            <activationType>P</activationType>
            <ruleTemplate>WorkflowDocumentTemplate</ruleTemplate>
        </requests>
        <process name="MyRadSubProcess" />
        <requests name="WorkflowDocument2">
            <activationType>P</activationType>
            <ruleTemplate>WorkflowDocument2Template</ruleTemplate>
        </requests>
        <requests name="WorkflowDocument3">
            <activationType>P</activationType>
            <ruleTemplate>WorkflowDocument3Template</ruleTemplate>
        </requests>
        <requests name="WorkflowDocumentFinal">
            <activationType>P</activationType>
            <ruleTemplate>WorkflowDocumentFinalTemplate</ruleTemplate>
        </requests>
    </routeNodes>
</documentType>

Figure 3.17. Move In Process Test

AdhocRouteTest

<documentType>
	<name>AdhocRouteTest</name>
	<description>AdhocRouteTest</description>
	<label>AdhocRouteTest</label>

	<postProcessorName>org.kuali.rice.kew.postprocessor.DefaultPostProcessor</postProcessorName>
	<superUserGroupName namespace=”KR-WKFLW” >TestWorkgroup</superUserGroupName>
	<blanketApproveGroupName namespace=”KR-WKFLW”>TestWorkgroup</blanketApproveGroupName>
	<defaultExceptionGroupName namespace=”KR-WKFLW”> TestWorkgroup</defaultExceptionGroupName>
	<docHandler>_blank</docHandler>
	<active>true</active>
	<routePaths>
		<routePath>
			<start name="AdHoc" nextNode="One" />
			<requests name="One" />
		</routePath>
	</routePaths>
	<routeNodes>
		<start name="AdHoc">
			<activationType>P</activationType>
		</start>
		<requests name="One">
			<activationType>S</activationType>
			<ruleTemplate>WorkflowDocumentTemplate</ruleTemplate>
		</requests>
	</routeNodes>
</documentType>

Figure 3.18. Adhoc Route Test

PreApprovalTest

<documentType>
    <name>PreApprovalTest</name>
    <description>PreApprovalTest</description>
    <label>PreApprovalTest</label>
    <postProcessorName>org.kuali.rice.kew.postprocessor.DefaultPostProcessor</postProcessorName>
    <superUserGroupName namespace=”KR-WKFLW” >TestWorkgroup</superUserGroupName>
    <blanketApproveGroupName namespace=”KR-WKFLW”>TestWorkgroup</blanketApproveGroupName>
    <defaultExceptionGroupName namespace=”KR-WKFLW”> TestWorkgroup</defaultExceptionGroupName>
    <docHandler>_blank</docHandler>
    <active>true</active>
    <routePaths>
        <routePath>
            <start name="AdHoc" nextNode="PreApprovalTestOne" />
            <requests name="PreApprovalTestOne" />
        </routePath>
    </routePaths>
    <routeNodes>
        <start name="AdHoc">
            <activationType>P</activationType>
        </start>
        <requests name="PreApprovalTestOne">
            <activationType>S</activationType>
            <ruleTemplate>WorkflowDocumentTemplate</ruleTemplate>
        </requests>
    </routeNodes>
</documentType>

Figure 3.19. PreApproval Test

VariablesTest

<documentType>
    <name>VariablesTest</name>
    <description>VariablesTest</description>
    <label>VariablesTest</label>

    <postProcessorName>org.kuali.rice.kew.postprocessor.DefaultPostProcessor</postProcessorName>
    <superUserGroupName namespace=”KR-WKFLW” >TestWorkgroup</superUserGroupName>
    <blanketApproveGroupName namespace=”KR-WKFLW”>TestWorkgroup</blanketApproveGroupName>
    <defaultExceptionGroupName namespace=”KR-WKFLW”> TestWorkgroup</defaultExceptionGroupName>
    <docHandler>_blank</docHandler>
    <active>true</active>
    <routePaths>
        <routePath>
            <start name="AdHoc" nextNode="setStartedVar" />
            <simple name="setStartedVar" nextNode="setCopiedVar"/>
            <simple name="setCopiedVar" nextNode="PreApprovalTestOne"/>
            <requests name="PreApprovalTestOne" nextNode="setEndedVar"/>
            <simple name="setEndedVar" nextNode="setGoogleVar"/>
            <simple name="setGoogleVar" nextNode="setXPathVar"/>
            <simple name="setXPathVar" nextNode="resetStartedVar"/>
            <simple name="resetStartedVar" nextNode="logNode"/>
            <simple name="logNode" nextNode="logNode2"/>
            <simple name="logNode2"/>
        </routePath>
    </routePaths>
    <routeNodes>
        <start name="AdHoc">
            <activationType>P</activationType>
        </start>
        <simple name="setStartedVar">
            <type>org.kuali.rice.kew.engine.node.var.SetVarNode</type>
            <name>started</name>
            <value>startedVariableValue</value>
        </simple>
        <simple name="setCopiedVar">
            <type>org.kuali.rice.kew.engine.node.var.SetVarNode</type>
            <name>copiedVar</name>
            <value>var:started</value>
        </simple>
        <requests name="PreApprovalTestOne">
            <activationType>S</activationType>
            <ruleTemplate>WorkflowDocumentTemplate</ruleTemplate>
        </requests>
        <simple name="setEndedVar">
            <type>org.kuali.rice.kew.engine.node.var.SetVarNode</type>
            <name>ended</name>
            <value>endedVariableValue</value>
        </simple>
        <simple name="setGoogleVar">
            <type>org.kuali.rice.kew.engine.node.var.SetVarNode</type>
            <name>google</name>
            <value>url:http://google.com</value>
        </simple>
        <simple name="setXPathVar">
            <type>org.kuali.rice.kew.engine.node.var.SetVarNode</type>
            <name>xpath</name>
            <value>xpath:concat(local-name(//documentContent),$ended)</value>
        </simple>
        <simple name="resetStartedVar">
            <type>org.kuali.rice.kew.engine.node.var.SetVarNode</type>
            <name>started</name>
            <value>aNewStartedVariableValue</value>
        </simple>
        <simple name="logNode">
            <type>org.kuali.rice.kew.engine.node.LogNode</type>
            <message>var:xpath</message>
        </simple>
        <simple name="logNode2">
            <type>org.kuali.rice.kew.engine.node.LogNode</type>
            <level>ErRoR</level>
            <log>Custom.Logger.Name</log>
            <message>THAT'S ALL FOLKS</message>
        </simple>
    </routeNodes>
</documentType>

Figure 3.20. Variables Test

SUApproveDocumentNotifications

<documentType>
    <name>SUApproveDocumentNotifications</name>
    <parent>SUApproveDocument</parent>
    <description>SUApproveDocumentNotifications</description>
    <label>SUApproveDocumentNotifications</label>

    <postProcessorName>org.kuali.rice.kew.postprocessor.DefaultPostProcessor</postProcessorName>
    <superUserGroupName namespace=”KR-WKFLW” >TestWorkgroup</superUserGroupName>
    <blanketApproveGroupName namespace=”KR-WKFLW”>TestWorkgroup</blanketApproveGroupName>
    <defaultExceptionGroupName namespace=”KR-WKFLW”> TestWorkgroup</defaultExceptionGroupName>
    <docHandler>_blank</docHandler>
    <active>true</active>
    <policies>
        <policy>
            <name>SEND_NOTIFICATION_ON_SU_APPROVE</name>
            <value>true</value>
        </policy>
    </policies>
</documentType>

The DISAPPROVE policy determines whether a document will discontinue routing (transactions). When a document has been disapproved, the document initiator and previous approvers will receive notice of this disapproval action.

The DEFAULT_APPROVE policy determines whether a document will continue processing with or without any approval requests. If a document is set to have no approval requests, its put into exception routing. Then, the document will continue to route to the exception workgroup associated with the last route node or to the workgroup defined in the defaultExceptionWorkgroupname.

The INITIATOR_MUST_ROUTE policy sets the rule that the user who initiates the document must route it.

The INITIATOR_MUST_SAVE policy sets the rule that the user who initiated the document will be the only one authorized to save the document.

The INITIATOR_MUST_CANCEL policy sets the rule that the user who initiated the document will be the only one authorized to cancel the document.

The INITIATOR_MUST_BLANKET_APPROVE policy sets the rule that the user who initiated the document is the only one authorized to blanket approve the document.

The LOOK_FUTURE policy determines whether the document can be brought into a simulated route from the route log. This policy simulates where the document would end up if it completed the route.

The SEND_NOTIFICATION_ON_SU_APPROVE policy indicates to KEW that it is to send a notification on SuperUser approval.

The SUPPORTS_QUICK_INITIATE policy indicates whether the Document Type is displayed on the Quick Links, so that users can quickly initiate instances of the document.

The NOTIFY_ON_SAVE policy indicates whether a notification should be sent in when a save action is applied to this Document Type.

The blanketApprovePolicy policy indicates who can blanket approve a workflow document. Its values are either ANY or NONE.

Alternatively, the configuration of the document can be set up to specify a blanketApproveWorkgroupName. blanketApproveWorkgroupName indicates that members of that workgroup can blanket approve the document. You can specify either blanketApprovePolicy OR blanketApproveWorkgroupName in the Document Type.

Since the blanket approve policy is not a true/false policy (like the others), it is specified as an element in the Document Type XML:

<documentType>
    <name>...</name>
    .
    .
    .
    <blanketApprovePolicy>NONE</blanketApprovePolicy>
</documentType>

There is currently the ability to override the "Perform Post Processor Logic" on the "Super User Action on Action Requests" page. This functionality is configurable by document type and as such allows for inheritance.

By default, the ALLOW_SU_POST_PROCESSOR_OVERIDE it's set to true. The checkbox appears on the super user screen as:

Figure 3.21. Super User Action on Requests

In order to turn off the post processor check box, you would add this to the documentType definition:

<policies>
    <policy>
        <name>ALLOW_SU_POSTPROCESSOR_OVERRIDE</name>
        <value>false</value>
    </policy>
</policies>

These fields are inherited:

Special notes about inheritance:

The Rules Engine follows these rules to determine its rule evaluation set for a Document Type at a particular node:

<name>YOURSERVICE-DOCS.RuleDocument</name>
<parent>YOURSERVICE-DOCS</parent>
<description>Add/Modify Workflow rules</description>
<label>Add/Modify Workflow rules</label>

The section above defines the Document Type's name, its parent, description, and label. The name is used by the client application’s API to communicate with KEW. Here is a sample of code from the client application’s API communicating with KEW:

WorkflowDocument document = new WorkflowDocument(new NetworkIdVO("username"), "DocumentTypeName");
document.routeDocument("user inputted annotation");

The above code will route a document in KEW.

<postProcessorName>your.package.routetemplate.RulePostProcessor</postProcessorName>

The element above determines which class to use for the PostProcessor for this particular Document Type. This component receives event notifications as eDocs travel through routing.

<superUserWorkgroupName>WorkflowAdmin</superUserWorkgroupName>
<blanketApproveWorkgroupName>WorkgroupBlanketApprovers</blanketApproveWorkgroupName>

<defaultExceptionWorkgroupName>WorkflowAdmin</defaultExceptionWorkgroupName>

This section sets KEW managed workgroups in several roles in the Document Type.

<docHandler>https://yourlocalIP/en-prd/Rule.do?methodToCall=docHandler</docHandler>

The docHandler tells KEW where to forward users when they click an eDoc link. See Document Search for more information.

<notificationFromAddress>...@yourEmailServerIP</notificationFromAddress>

When KEW sends an email notification to a user regarding a document of this type, the From address on the message is the address specified here. This is helpful because users will often reply to the messages they receive from KEW, and this allows their responses to go to an appropriate address for the Document Type. This is an optional element. If it is not defined here, KEW uses the default From address. See the Installation Guide for more detail.

<active>true</active>

Use active to define the activeness of a Document Type. KEW does not allow anyone to create eDocs of an inactive Document Type.

<routePaths>
    <routePath>
        <start name="Adhoc Routing" nextNode="Rule routing Route Level" />
        <requests name="Rule routing Route Level" />
    </routePath>
</routePaths>

The above defines the path an eDoc will travel as it progresses through its life. Start and Requests are some of the standard node types used. There is only one stop each eDoc must make as it travels through workflow. The eDoc starts at the step Adhoc Routing and then progresses to the request node named Rule routing Route Level.

This section only defines the path the eDocs will travel. The nodes themselves are defined below.

<routeNodes>
    <start name="Adhoc Routing">
        <activationType>S</activationType>
        <mandatoryRoute>false</mandatoryRoute>
        <finalApproval>false</finalApproval>
    </start>
    <requests name="Rule routing Route Level">
        <activationType>S</activationType>
        <ruleTemplate>RuleRoutingTemplate</ruleTemplate>
        <mandatoryRoute>true</mandatoryRoute>
        <finalApproval>false</finalApproval>
    </requests>
</routeNodes>

This is the node definition XML. This determines certain behaviors each node can have.

Activation Type determines if Approve requests are activated all at once or one at a time. Any given requests node can generate multiple rules that can then generate multiple requests. The ActivationType value specifies if all action requests generated for all fired rules are activated immediately (P = parallel activation), or if the set of action requests generated by each rule are activated one after the other, according to rule order (S = sequential activation). Activation type is only relevant when multiple rules are generated.

Figure 3.22. Activation Type

The mandatoryRoute key determines if it’s mandatory to generate approval requests. If a route node is mandatory and it doesn't generate an approve request, the document is put in exception routing.

The finalapproval key determines if this node should be the last node that has an approve request. If approvals are generated after this step, the document is thrown into exception routing.

Finally, there is a request node named Rule routing Route Level with a key called ruleTemplate. This is our hook into the rule system for KEW:

<ruleTemplate>RuleRoutingTemplate</ruleTemplate>

And this is our hook into a route module:

<routeModule>package.your.ARouteModule</routeModule>

KEW contacts the route module when the document enters that route node and the route module returns Action Requests for KEW to deliver.

If the application integrating with KEW is using Rules to contain the routing data and RuleAttributes for document evaluation, then the routing configuration requires more XML. Below is an XML snippet that defines RuleAttribute; this is written in Java.

<?xml version="1.0" encoding="UTF-8"?>
<data xmlns="ns:workflow" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="ns:workflow resource:WorkflowData">
    <ruleAttributes XMLns="ns:workflow/RuleAttribute" xsi:schemaLocation="ns:workflow/RuleAttribute resource:RuleAttribute">
        <ruleAttribute>
            <name>RuleRoutingAttribute</name>
            <className>org.kuali.rice.kew.rule.RuleRoutingAttribute</className>
            <label>RuleRoutingAttribute</label>
            <description>RuleRoutingAttribute</description>
            <type>RuleAttribute</type>
        </ruleAttribute>
    </ruleAttributes>
</data>

The above defines a RuleAttribute called RuleRoutingAttribute. RuleRoutingAttribute maps to the Java class org.kuali.rice.kew.rule.RuleRoutingAttribute. The type of this attribute is a RuleAttribute; essentially this means the RuleAttribute's behavior is determined in a Java class. There are also RuleAttributes made entirely from XML, but programming attributes is outside the scope of this Guide.

Finally, we need to tie the RuleAttribute to the Document Type. This is done using the RuleTemplate and it is defined using XML. The RuleTemplate schema below provides further explanation:

<?xml version="1.0" encoding="UTF-8"?>

<data xmlns="ns:workflow" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="ns:workflow resource:WorkflowData">
    <ruleTemplates XMLns="ns:workflow/RuleTemplate" xsi:schemaLocation="ns:workflow/RuleTemplate resource:RuleTemplate">
        <ruleTemplate>
            <name>RuleRoutingTemplate</name>
            <description>RuleRoutingTemplate</description>
            <attributes>
                <attribute>
                    <name>RuleRoutingAttribute</name>
                    <required>true</required>
                </attribute>
            </attributes>
        </ruleTemplate>
    </ruleTemplates>
</data>

<attributes>
    <attribute>
        <name>RuleRoutingAttribute</name>
        <required>true</required>
    </attribute>
</attributes>

The RuleTemplate is the join between RuleAttributes and Document Types. In this way, we can reuse the same attribute declaration (and therefore Java logic) across Document Types.

Once the XML, condensed into a single file, is uploaded into KEW, eDocs of this type can be created and routed from a client application.

All the content in the code examples above is aggregated into a single file below with a single surrounding data tag:

<?xml version="1.0" encoding="UTF-8"?>
<data xmlns="ns:workflow" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="ns:workflow resource:WorkflowData">
    <ruleAttributes xmlns="ns:workflow/RuleAttribute" xsi:schemaLocation="ns:workflow/RuleAttribute resource:RuleAttribute">
        <ruleAttribute>
            <name>RuleRoutingAttribute</name>
            <className>org.kuali.rice.kew.rule.RuleRoutingAttribute</className>
            <label>foo</label>
            <description>foo</description>
            <type>RuleAttribute</type>
        </ruleAttribute>
    </ruleAttributes>
    <ruleTemplates xmlns="ns:workflow/RuleTemplate" xsi:schemaLocation="ns:workflow/RuleTemplate resource:RuleTemplate">
        <ruleTemplate>
            <name>RuleRoutingTemplate</name>
            <description>RuleRoutingTemplate</description>
            <attributes>
                <attribute>
                    <name>RuleRoutingAttribute</name>
                    <required>true</required>
                </attribute>
            </attributes>
        </ruleTemplate>
    </ruleTemplates>
    <documentTypes xmlns="ns:workflow/DocumentType" xsi:schemaLocation="ns:workflow/DocumentType resource:DocumentType">
        <documentType>
            <name>EDENSERVICE-DOCS.RuleDocument</name>
            <parent>EDENSERVICE-DOCS</parent>
            <description>Add/Modify Workflow rules</description>
            <label>Add/Modify Workflow rules</label>
            <postProcessorName>org.kuali.rice.kew.postprocessor.RulePostProcessor</postProcessorName>
            <superUserGroupName namespace=KR-WKFLW”>WorkflowAdmin</superUserGroupName>
            <blanketApproveGroupName namespace=KR-WKFLW”>WorkflowAdmin</blanketApproveGroupName>
            <defaultExceptionGroupName></defaultExceptionGroupName>
            <docHandler>https://uisapp2.iu.edu/en-prd/Rule.do?methodToCall=docHandler</docHandler>
            <active>true</active>
            <routingVersion>1</routingVersion>
            <routePaths>
                <routePath>
                    <start name="Adhoc Routing" nextNode="Rule routing Route Level" />
                    <requests name="Rule routing Route Level" />
                </routePath>
            </routePaths>
            <routeNodes>
                <start name="Adhoc Routing">
                    <activationType>S</activationType>
                    <mandatoryRoute>false</mandatoryRoute>
                </start>
                <requests name="Workflow Document Routing">
                    <activationType>S</activationType>
                    <ruleTemplate>RuleRoutingTemplate</ruleTemplate>
                    <mandatoryRoute>true</mandatoryRoute>
                </requests>
            </routeNodes>
        </documentType>
    </documentTypes>
</data>

You name the routing node with the name attribute, just like for a rule-based routing node.

The qualifier resolver finds any qualifiers that need to be used while matching the responsibility. You can specify it in either of two ways:

You can specify <responsibilityTemplateName>name</responsibilityTemplateName> to identify the responsibility template to use. This option is not usually used since all of the responsibilities provided with KIM use a template named Review.

You can specify <namespace>name</namespace> to identify the name space for the responsibility. This option is usually not used since all of the responsibilities provided with KIM use a name space of KR-WKFLW.