Where do I get it from?
For now you need to get the source code from:
Anonymous subversion http://anonsvn.jboss.org/repos/tohu/trunk
The best idea to get started is to check out from the tag as this is in a known good state with all of the examples working.
How do I get it running?
It uses Maven. You can just build the examples from the examples directory with:
mvn clean install
and then run them from each x-example-web directory using:
Then browse to
What background knowledge do I need to be able to use this?
It is based on Drools so it helps if you are familiar with that or at least other rules engines.
Where is the best place to start?
The best idea is to run the examples and have a look at the code. Start with simple-example because each rule is explained in the code (
See also: Tohu - Examples
How much code do I actually have to write?
The bare minimum needed for a working Tohu application (using the JQuery client) is:
- rules to define your questions and their interaction
- a wrapper HTML page (or JSP) to embed the dynamic UI in (which could be just a few lines)
- a servlet to do something useful with the data captured. (Most of the examples just generate a PDF but you can of course do anything with the data, and this is simplified by using DomainModelAssociation to link directly to POJOs.)
- some basic CSS to make it look nice
And thats it!
And if you want to populate your forms with existing data (e.g. if the user returns later to make changes) then you need some code to feed the data in as well. (See domain-example as one way to do this using POJOs.)
How does it work?
What do the various modules do?
See: Tohu - Modules
What do I do if I find a bug?
If something is broken we want to know. Please raise bugs in Jira: https://jira.jboss.org/jira/browse/TOHU
My dependent question appears when it should but then it won't disappear again. Why?
This is probably because you have used
insert instead of
insertLogical. If you use
insertLogical then Drools will automatically retract the fact again when the particular condition is no longer true. This is called truth-maintenance.
If you have used
insertLogical but it still isn't working then your
when clause probably uses a condition that is always true so you'll need to revise the logic to make it work nicely.
Why does a group specify all children in the setItems method, even when some children may not be displayed based on other rules?
Any children items that are listed but not actually inserted are ignored by the User Interface Library. This is deliberate, as it greatly simplifies the logic around setting up relationships between parents and children – see below.
Why are the children of a group specified in the group itself? Can I take a bottom up type approach?
While there is an aspect of having the list of children specified in the parent object that feels slightly odd, it turns out that it is the simplest and most effective way of setting the rules up. However, if you want to write rules whereby children attach themselves to parent objects, this can be done using
at the point where the child is defined instead of
See loyalty-complex-example as an example using this approach.
Why is there no explicit concept of pages?
This was a deliberate decision. The idea was that the Questionnaire should model the information that we wished to capture from the user and the interrelationships between the various questions, but not care about the presentation of that information. Displaying the questions as a number of different pages is solely a presentation decision. The different top-level groups within a Questionnaire could equally well be displayed as a series of tabs, or as a number of vertically expanding/collapsing sections on the screen. Thus the concept of pages does not appear in the questionnaire model itself.
The JQuery client implementation currently only supports pages and not these other ways of presenting the data, but by keeping the model generic it allows for this in the future, either in the JQuery client or in other clients e.g. a desktop application
Why do all the examples consist of 2 separate projects? Do I have to do it that way?
The reason for the separation is to make it easier to deploy the rules to the BRMS (Guvnor) instead of bundling them into the web application. If you are happy to treat your rules as code (and manage them as part of your normal software development lifecycle) then there is no problem putting everything in one project. Externalising them as assets available to the BRMS gives more flexibility around changes to the rules.
How do I turn on validation for each top-level group within a questionnaire?
When one is configuring a Questionnaire through the rules, there is an option on the Questionnaire which allows one to enable/disable validation. The option is called "enableActionValidation". See the Questionnaire Domain Object for this option.
How do I turn on logging for the Tohu artifacts.
Tohu is currently built using the maven toolset. Each Tohu framework artifact references its own maven customised property to determine their log level. The default logging level has being set to "INFO". One can override the log level for each Tohu artifact separately by adding the appropriate maven customised property to their active maven profile. This is usually located and configured in the settings.xml which is installed as part of the Maven installation process. Remembering that in maven the profile property settings will override those set in any POM files.
The Tohu Loader artifact's POM contains this default property used by its log4j.properties resource.
To override this to use debug mode, then it is advised to update your active maven profile. Noting it must be the active one. See maven documentation on how to determine the active profile.
If one is using another type of build tool apart from Maven, e.g Apache Ant. Then all one needs to know is that your build process which generates the Tohu artifacts needs to substitute certain values in the projects log4j.properties when this log4j.properties is being added to the generated artifact.
Why does my app work with mvn jetty:run but not when I deploy the war to an app server?
If you are getting the error "An error has occured calling the rules server, refresh the page and try again" then this is probably because your agent config file uses file:src/main/rules to specify the location of one or more of the drl files. This works with mvn jetty:run but won't work when you use the war file.
You can fix by changing the location to classpath:rules or if you need to be able to dynamically change the rules then use BRMS or an external file: path.
Note that the SpreadsheetBiology and SpreadsheetLoyaltyGold examples are configured like this so that the server picks up changes to the rules from editing the spreadsheet. Projects created with tohu-archetype also do this.