Running the Example App

OSWorkflow comes with a very simple example application to help you get started with understanding the concepts OSWorkflow is based upon. The example application has been deployed and tested on the following app servers: Orion 1.5.4, JBoss 2.4.4, WebLogic 6.1 & 7.0 and Pramati 3.0. If your application server isn't supported, you can learn how to modify the example app below so that it will deploy in any servlet container.

This example app has been configured to use the DataSource with the JNDI location jdbc/DefaultDS. If your datasource differs and you cannot create a datasource with this name, you'll need to edit your deployment descriptors accordingly.

Classpath Issues

The most important part to getting the example EAR to deploy and run is ensuring your config files and libraries have been placed in a classpath that the application can see. The following config files must be in your classpath: osuser.xml, osworkflow.xml, workflows.xml, and test.xml. The library bsh-1.2b5.jar must also be in the classpath for OSWorkflow to function.

Orion

In Orion, the EAR will deploy with these classpath issues automatically resolved, due to the library tag in orion-application.xml. There is nothing that needs to be done. We recommend using Orion as the quickest way to get OSWorkflow running.

JBoss

In JBoss, we recommend putting the above files in your jboss/lib/ext directory to quickly get the example application running. Besides this, you must also configure JBoss to use the authentication realm osuser. This can be done by editing jboss/config/catalina/auth.conf and adding the following entry:

osuser {
   org.jboss.security.auth.spi.ProxyLoginModule required
   moduleName=com.opensymphony.module.user.adapter.jboss.OSUserLoginModule;
};

In addition to this change, osuser.jar and oscore.jar must be placed in the JBoss classpath, preferably also in jboss/lib/ext.

Pramati Application Server

Just as in JBoss, you must place the configuration files and the BeanShell library somewhere in the application server's classpath. This can be done by editing server/bin/setup.bat and adding new entries to the CLASSPATH. Pramati must also include osuser.jar and oscore.jar, so that the Pramati-OSUser integration can be enabled. This can be done by adding a new security realm with the following settings:

	LoginModule: com.opensymphony.module.user.adapter.pramati.PramatiLoginModule
	LoginModule options: realmname=osuser
	

	UserManager: com.opensymphony.module.user.adapter.pramati.PramatiUserManager

WebLogic 6.1 & 7.0

Because there is no OSUser adapter available for WebLogic yet, OSWorkflow support for WebLogic is listed as "partial". Getting the example application to run is actually fairly easy however: ensure that your classpath is set correctly (as stated above) and then deploy the example EAR. Because OSUser isn't ingegrated with WebLogic, you'll need to create the same user twice: once as outlined below in the OSUser manager application, and once in the WebLogic admin console.

Required User Management Settings

The OSWorkflow example application excepts that there are three groups created in the OSUser UserManager: foos, bars, and bazs. You can create these groups by accessing the manager web-app, usually found at http://localhost/manager. You will need to also create a user, such as "test", that is in these groups. This will be the user you will log in as.

Please note that getting your application server to talk to OSUser successfully might be a little difficult at first, especially when using the Pramati application server. Usually redeploying the application again resolves these problems.

Non-EJB Installation

If you can't use one of these supported applications servers and are unable to deploy the EJBs to your app server, you can still run the example application by making a few modifications to the EAR. First, you'll want to move osuser.jar, oscore.jar, and osworkflow.jar to the WEB-INF/lib directories in both web-applications. Please understand that this method is unsupported, but we have successfully done it ourselves and it should work for you too with a bit of effort. We still, however, recommend using one of the above app servers to get a feel for OSWorkflow.

Next, you'll want to edit osworkflow.xml and osuser.xml and switch the persistence types to use "ofbiz" instead of EJB. You will find the changes needed in the files commented out.

Next, you'll need to create a way for the user your created that belonged to the groups mentioned above to be able to log in. Since your app server may not have an adapter to OSUser, you may need to create a user that can log in. The key is that the same username that is logging in ("test" for example) is also the username that belongs to the aforementioned groups. Alternatively, you may hardcode the username to the JSPs mentioned below and edit web.xml to remove all security-constraints.

You'll also need to copy the Ofbiz deployment descriptors to WEB-INF/classes. You may need to edit entityengine.xml to work with your application server's JTA implementation as well as configure your datasource.

Next, you'll need to copy the BeanShell library to WEB-INF/lib.

Lastly, you'll need to edit newworkflow.jsp and test.jsp and make these JSPs use the OfbizWorkflow implementation instead of the EJBWorkflow implementation. The constructor of OfbizWorkflow takes the username with which to work with. If you are having difficulty getting your app server to work with OSUser, you may hardcode this value to the username you created using the OSUser manager.