JBoss.orgCommunity Documentation

Guvnor User Guide

For users and administrators of Guvnor

Version 5.5.0.Final

Abstract

This manual provides complete documentation for Guvnor.


1. Introduction
1.1. What is a Business Rules Manager?
1.1.1. When to use Guvnor
1.1.2. Who uses Guvnor
1.2. Features outline
I. User Guide
2. Quick Start Guide
2.1. Quick start guide
2.1.1. Supported browser platforms
2.1.2. Initial configuration
2.1.3. Writing a rule
2.1.4. Finding stuff
2.1.5. Deployment
3. Concepts
3.1. Rules are assets
3.2. Packages are assets
3.3. Perspectives
3.4. The business user perspective
3.4.1. Creating a business user view
4. Authoring Assets
4.1. Version management
4.2. The Asset Editor
4.3. Creating a package
4.3.1. Empty package
4.3.2. Importing DRL packages
4.4. Spring Contexts
4.5. Working Sets
4.5.1. Activating and Using Working Sets
4.6. Business rules with the guided editor
4.6.1. Parts of the Guided Rule Editor
4.6.2. The "WHEN" (left-hand side) of a Rule
4.6.3. The "THEN" (right-hand side) of a Rule
4.6.4. Optional attributes
4.6.5. Pattern/Action toolbar
4.6.6. User driven drop down lists
4.6.7. Augmenting with DSL sentences
4.6.8. A more complex example:
4.7. DSL rules
4.8. Technical rules (DRL)
4.9. Spreadsheet decision tables
4.10. Guided decision tables (web based)
4.10.1. Types of decision table
4.10.2. Main components\concepts
4.10.3. Defining a web based decision table
4.10.4. Rule definition
4.10.5. Audit Log
4.11. Templates of assets/rules
4.11.1. Creating a rule template
4.11.2. Define the template
4.11.3. Defining the template data
4.11.4. Generated DRL
4.12. The Fact Model
4.12.1. Ways to define a Fact Model
4.12.2. Creating a JAR Model
4.12.3. Declarative model
4.13. Functions
4.14. DSL editor
4.15. Rule flows
4.16. BPMN2 Process
4.17. Work Item Definition
4.18. Data enumerations (drop down list configurations)
4.18.1. Advanced enumeration concepts
4.19. Test Scenario
4.19.1. Given Section
4.19.2. Expect Section
4.19.3. Global Section
4.19.4. New Input Section
4.19.5. Audit Log
4.20. File
4.21. Change-Set
4.21.1. Change-Set Editor UI
4.21.2. Adding Packages using a Wizard
4.21.3. Adding Assets using a Wizard
4.22. Services
4.22.1. Configuring Multiple Knowledge Bases
4.22.2. Knowledge Base Configuration Panel
4.22.3. Downloading War & Managing Dependencies
4.23. **INCUBATOR FEATURE** New Rule Asset - Scorecards
4.23.1. (a) Setup Parameters
4.23.2. (b) Characteristics
5. Managing Assets
5.1. Navigating and finding rules
5.1.1. Package explorer
5.1.2. Category view
5.1.3. Inbox and comments
5.2. Feed
6. Quality Assurance
6.1. Test scenarios
6.2. Package analysis
6.2.1. Items that the analyser is searching for
7. Packaging
7.1. Packaging
7.2. Imports and Globals
7.2.1. Basic View
7.2.2. Advanced View
7.3. Category rules
7.4. Building
7.5. Selectors
7.5.1. Built-in Selector
7.5.2. Custom Selector
7.6. Snapshots
7.7. Advanced configuration
8. Administrative Functions
8.1. Categories
8.2. Status management
8.3. Archived items
8.4. Event Log
8.5. User permissions
8.6. Import and Export
8.7. Repository Configuration
II. Developer Guide
9. Integrating rules with your applications
9.1. The Knowledge Agent
9.2. REST API
9.2.1. REST
9.2.2. Guvnor REST API
9.2.3. Source code Example
9.3. WebDAV and HTTP
9.3.1. WebDAV
9.3.2. URLs
9.4. Eclipse Guvnor integration
9.4.1. Source Code and Plug-in Details
9.4.2. Functionality Overview
9.4.3. Guvnor Connection Wizard
9.4.4. Guvnor Repository Explorer
9.4.5. Local Copies of Guvnor Files
9.4.6. Actions for Local Guvnor Resources
9.4.7. Importing Guvnor Repository Resources
9.4.8. Guvnor plugin Preferences
10. Embedding Guvnor In Your Application
10.1. Getting Started
10.2. Embedded Editor Entry-Point: StandaloneEditorServlet
10.3. Edition Modes
10.3.1. BRL Edition Mode
10.3.2. Edition of Existing Assets Mode
10.3.3. New Asset Mode
10.4. Extra HTTP parameters
10.4.1. Rule’s Sections Visibility Parameters
10.4.2. Constraining Fact Types
10.4.3. Use existing Working-Sets
10.5. Interacting with the Editor
III. Administration Guide
11. Installation
11.1. Installation step by step
11.2. Supported and recommended platforms
12. Database configuration
12.1. Changing the location of the data store
12.2. Configuring Guvnor to use an external RDBMS
12.3. Searching and indexing, Version storage
13. Switch from JackRabbit to ModeShape
14. Security - Authentication and basic access
14.1. Using your containers security and LDAP
15. Fine grained permissions and security
15.1. Enabling fine grained authorization
16. Data management
16.1. Backups
16.2. Repository Data Migration
16.3. Adding your own logos or styles to Guvnor web GUI
16.4. Import and Export
17. Architecture
17.1. Building from source
17.1.1. Modules
17.1.2. Working with Maven 2
17.1.3. Working with GWT
17.1.4. Debugging, Editing and running with Eclipse
17.2. Re-usable components
17.3. Versioning and Storage
17.4. Contributing

This section introduces Guvnor. See the other relevant sections for installation, usage and administration.


A business rules manager allows people to manage rules in a multi user environment, it is a single point of truth for your business rules, allowing change in a controlled fashion, with user friendly interfaces.

Guvnor is the name of the web and network related components for managing rules with drools. This combined with the core drools engine and other tools forms the business rules manager.

This part covers Guvnor for end-users.

Table of Contents

2. Quick Start Guide
2.1. Quick start guide
2.1.1. Supported browser platforms
2.1.2. Initial configuration
2.1.3. Writing a rule
2.1.4. Finding stuff
2.1.5. Deployment
3. Concepts
3.1. Rules are assets
3.2. Packages are assets
3.3. Perspectives
3.4. The business user perspective
3.4.1. Creating a business user view
4. Authoring Assets
4.1. Version management
4.2. The Asset Editor
4.3. Creating a package
4.3.1. Empty package
4.3.2. Importing DRL packages
4.4. Spring Contexts
4.5. Working Sets
4.5.1. Activating and Using Working Sets
4.6. Business rules with the guided editor
4.6.1. Parts of the Guided Rule Editor
4.6.2. The "WHEN" (left-hand side) of a Rule
4.6.3. The "THEN" (right-hand side) of a Rule
4.6.4. Optional attributes
4.6.5. Pattern/Action toolbar
4.6.6. User driven drop down lists
4.6.7. Augmenting with DSL sentences
4.6.8. A more complex example:
4.7. DSL rules
4.8. Technical rules (DRL)
4.9. Spreadsheet decision tables
4.10. Guided decision tables (web based)
4.10.1. Types of decision table
4.10.2. Main components\concepts
4.10.3. Defining a web based decision table
4.10.4. Rule definition
4.10.5. Audit Log
4.11. Templates of assets/rules
4.11.1. Creating a rule template
4.11.2. Define the template
4.11.3. Defining the template data
4.11.4. Generated DRL
4.12. The Fact Model
4.12.1. Ways to define a Fact Model
4.12.2. Creating a JAR Model
4.12.3. Declarative model
4.13. Functions
4.14. DSL editor
4.15. Rule flows
4.16. BPMN2 Process
4.17. Work Item Definition
4.18. Data enumerations (drop down list configurations)
4.18.1. Advanced enumeration concepts
4.19. Test Scenario
4.19.1. Given Section
4.19.2. Expect Section
4.19.3. Global Section
4.19.4. New Input Section
4.19.5. Audit Log
4.20. File
4.21. Change-Set
4.21.1. Change-Set Editor UI
4.21.2. Adding Packages using a Wizard
4.21.3. Adding Assets using a Wizard
4.22. Services
4.22.1. Configuring Multiple Knowledge Bases
4.22.2. Knowledge Base Configuration Panel
4.22.3. Downloading War & Managing Dependencies
4.23. **INCUBATOR FEATURE** New Rule Asset - Scorecards
4.23.1. (a) Setup Parameters
4.23.2. (b) Characteristics
5. Managing Assets
5.1. Navigating and finding rules
5.1.1. Package explorer
5.1.2. Category view
5.1.3. Inbox and comments
5.2. Feed
6. Quality Assurance
6.1. Test scenarios
6.2. Package analysis
6.2.1. Items that the analyser is searching for
7. Packaging
7.1. Packaging
7.2. Imports and Globals
7.2.1. Basic View
7.2.2. Advanced View
7.3. Category rules
7.4. Building
7.5. Selectors
7.5.1. Built-in Selector
7.5.2. Custom Selector
7.6. Snapshots
7.7. Advanced configuration
8. Administrative Functions
8.1. Categories
8.2. Status management
8.3. Archived items
8.4. Event Log
8.5. User permissions
8.6. Import and Export
8.7. Repository Configuration

If you are reading this, you must be the impatient type who wants to kick the tires (and light the fires) and have a look around as soon as possible. This section will provide a quick end to end tour of the steps involved (but does not go through the concepts in detail). This assumes you have installed the repository correctly, and are able to access the main login screen.

You can also consult the wiki for some tutorials and user tips (it IS a wiki, so you can even contribute your own tips and examples and even upload files if you desire !).


The above picture shows the main feature areas of Guvnor.

  • Info: This is the initial screen, with links to resources.

  • Rules: This is the category and business user perspective.

  • Package: This is where packages are configured and managed.

  • Deployment: this is where deployment snapshots are managed.

  • Admin: Administrative functions (categories, statuses, import and export)

Some initial setup is required the first time. The first time the server starts up, it will create an empty repository, then take the following steps:

  • Once deployed, go to http://localhost:8080/guvnor-5.5.0.Final/ This will show the initial info screen or login screen depending on the configuration.

  • If it is a brand new repository, you will want to go to "Admin", and choose "Manage Categories"

    (Add a few categories of your choosing, categories are only for classification, not for execution or anything else and are optional, but recommended).

  • Rules and other assets belong to a Package, a container for related artifacts.

    • Select the "Knowledge Bases" section of the menu-bar on the left-hand side of the Guvnor main window.

    • Click on "Create New" to show the types of asset that can be created and select "New Package". Click on "Create new package" and enter a suitable name.

    • Click "Create package".

  • Rules need a fact model (object model) to work. The model defines your domain artifacts representing the knowledge you wish to manage.

    • Select the "Knowledge Bases" section of the menu-bar on the left-hand side of the Guvnor main window.

    • Click on "Create New" and select "Upload POJO model JAR" (if you have a JAR containing your Java model).

    • Enter a suitable name and ensure the package you defined above is selected in the "Create in package" dropdown.

    • Click OK

    • The POJO Upload screen is displayed.

    • Click on "Browse" and select your JAR file.

    • Click on "Upload".

  • At this point, the package is configured and ready to go (you generally won't have to go through that step very often).

    (Note that you can also import an existing DRL package - it will store the rules in the repository as individual assets).

You can see from this manual, that some expertise and practice is required to use Guvnor. In fact any software system in some sense requires that people be "technical" even if it has a nice looking GUI. Having said that, in the right hands Guvnor can be setup to provide a suitable environment for non technical users.

The most appropriate rule formats for this use are using the Guided editor, Decision tables and DSL rules. You can use some DSL expressions also in the guided editor (so it provides "forms" for people to enter values).

You can use categories to isolate rules and assets from non technical users. Only assets which have a category assigned will appear in the "categories" view.

The initial setup of Guvnor will need to be done by a developer/technical person who will set the foundations for all the rules. They may also create "templates" which are rules which may be copied (they would typically live in a "dummy" package, and have a category of "template" - this can also help ease the way).

Deployment should also not be done by non technical users (as mentioned previously this happens from the "Package" feature).

4.1. Version management
4.2. The Asset Editor
4.3. Creating a package
4.3.1. Empty package
4.3.2. Importing DRL packages
4.4. Spring Contexts
4.5. Working Sets
4.5.1. Activating and Using Working Sets
4.6. Business rules with the guided editor
4.6.1. Parts of the Guided Rule Editor
4.6.2. The "WHEN" (left-hand side) of a Rule
4.6.3. The "THEN" (right-hand side) of a Rule
4.6.4. Optional attributes
4.6.5. Pattern/Action toolbar
4.6.6. User driven drop down lists
4.6.7. Augmenting with DSL sentences
4.6.8. A more complex example:
4.7. DSL rules
4.8. Technical rules (DRL)
4.9. Spreadsheet decision tables
4.10. Guided decision tables (web based)
4.10.1. Types of decision table
4.10.2. Main components\concepts
4.10.3. Defining a web based decision table
4.10.4. Rule definition
4.10.5. Audit Log
4.11. Templates of assets/rules
4.11.1. Creating a rule template
4.11.2. Define the template
4.11.3. Defining the template data
4.11.4. Generated DRL
4.12. The Fact Model
4.12.1. Ways to define a Fact Model
4.12.2. Creating a JAR Model
4.12.3. Declarative model
4.13. Functions
4.14. DSL editor
4.15. Rule flows
4.16. BPMN2 Process
4.17. Work Item Definition
4.18. Data enumerations (drop down list configurations)
4.18.1. Advanced enumeration concepts
4.19. Test Scenario
4.19.1. Given Section
4.19.2. Expect Section
4.19.3. Global Section
4.19.4. New Input Section
4.19.5. Audit Log
4.20. File
4.21. Change-Set
4.21.1. Change-Set Editor UI
4.21.2. Adding Packages using a Wizard
4.21.3. Adding Assets using a Wizard
4.22. Services
4.22.1. Configuring Multiple Knowledge Bases
4.22.2. Knowledge Base Configuration Panel
4.22.3. Downloading War & Managing Dependencies
4.23. **INCUBATOR FEATURE** New Rule Asset - Scorecards
4.23.1. (a) Setup Parameters
4.23.2. (b) Characteristics

The Asset Editor is the principle component of Guvnor's User-Interface. It consists of two tabs:-

Configuring packages is generally something that is done once, and by someone with some experience with rules/models. Generally speaking, very few people will need to configure packages, and once they are setup, they can be copied over and over if needed. Package configuration is most definitely a technical task that requires the appropriate expertise.

All assets live in "packages" in the Guvnor - a package is like a folder (it also serves as a "namespace"). A home folder for rule assets to live in. Rules in particular need to know what the fact model is, what the namespace is etc.

So while rules (and assets in general) can appear in any number of categories, they only live in one package. If you think of the Guvnor as a file system, then each package is a folder, and the assets live in that folder - as one big happy list of files. When you create a deployment snapshot of a package, you are effectively copying all the assets in that "folder" into another special "folder".

To create an empty package select "New Package" from the "Create new" (asset) menu.


Working Sets are a mean for grouping Facts and then defining constraints on them. You can create groups of Facts and only those Facts will be visible when authoring rules using the Guided Editor.

Right now, Working Sets must be activated manually from the Guided Editor window (using the "Select Working Set" button placed in the toolbar). In the future, different Working Sets could be assigned to different users to reduce the scope and complexity when authoring rules.


The figure above shows the window used to create or modify Working Sets. In this window you will find 2 lists. The list on the left side contains the possible Fact Types that can be added to the Working Set. These facts are those defined/imported in the package's model. The list on the right side contains the allowed Fact Types of this Working Set. When this Working Sets is active, only those Fact Types could be used while authoring rules using the Guided BRL Editor


Once you have selected the valid Fact Types for a Working Set, you can add Constraints to the fields of those Facts Types. The image above shows how the Field Constraint tab looks like. In this configuration screen you will find:

A.- Fact Types dropdown: Here you will find a list containing the Working Set's Fact Types

B.- Field dropdown: Once you have selected a Fact Type, this dropdown will contain its fields.

C.- Constraints List: This lists shows all the Constraints applied to the selected Field

D.- Action Buttons: Using these buttons you will be able to add or remove Constraints to the selected Field. Right now, Guvnor provides a built-in collection of Constraints. The idea for next releases is to let users to plug their custom Constraints too.

E.- Constraint's Attributes: In this section you will find all the attributes of the current Constraint that could be parametrized by the user.

In the example above, a Matches Constraint is created for Car.brand field. This means that when rule authors use this field in a Rule condition, they should use a value valid according to this constraint, otherwise they will receive an error or warning.

Working Sets are no active by default in Guvnor. Because this is an experimental feature, you must enable them manually in the Guided Editor panel if you want to use them. In the future, Working Sets will be associated to each user's profile.

A new button was added in Guided Editor's Toolbar: "Select Working Sets". This button will open a popup with the list of the package's Working Sets. Using this popup you can activate one or more Working Sets.

When Working Sets are activated, only the Fact Types allowed by them could be used when inserting new Patterns or Actions. The Patterns and Actions already present in the rule that contain prohibited Fact Types are marked as read only. Take a look at the next screen shots comparing the Guided Editor panel with and without Working Sets


In the image you can see how Working Sets could help rule's authors by reducing the amount of available Fact Types


Here you can see how Patterns containing prohibited Fact Types are switched to read only mode after Working Sets are activated.

Up to now we have only cover how Facts are filtered using Working Sets. Another important feature of Working Sets is Field Constraints. We have already saw how to configure them, now we are going to explain how to use them.

Because Field Constraints are defined inside a Working Set, we need to activate one or more Working Set to start working with them. Once a Working Set defining Field's Constraints is active we have two ways to use them: on demand validation and real-time validation.

On demand validation is performed when you press the "Verify" button present in Guided Editor's toolbar. This button will fire a rule verification and will end up showing a report with the results. Any violated constraint will be shown as an error or warning according to its relevance


The image above shows the report that appears when a Working Set defines a Range Constraint on Driver.age. The age should be between 18 and 80.

Real-Time validation is an experimental feature (yes, inside another experimental feature like Working Sets) that checks for Field's Constraints violations in real time and mark the lines where the violations are using error or warning icons. This feature is disabled by default because sometimes it could be expensive. If you want to try it out, you should enable it in Administration -> Rules Verification. This configuration is not yet persisted, so you need to enable it every time you start Guvnor.


This Image shows the result of real-time validation. There you can see the same result as on demand validation, but you don't need to click any button, and the errors/warnings are shown in a more fashionable way!

Warning

The problem with real-time validation is that right now only support "top level" Patterns.

Business Rules authored with the Guided Editor are more commonly known as "BRL Rules".

These rules use the guided GUI which controls and prompts user input based on knowledge of the object model.

This can also be augmented with DSL sentences.

B : This shows a pattern which is declaring that the rule is looking for a "LoanApplication" fact (the fields are listed below, in this case none). Another pattern, "Applicant", is listed below "LoanApplication". Fields "creditRating" and "applicationDate" are listed. Clicking on the fact name ("LoanApplication") will pop-up a list of options to add to the fact declaration:-

C : The "minus" icon ("[-]") indicates you can remove something. In this case it would remove the whole "LoanApplication" fact declaration. Depending upon the placement of the icon different components of the rule declaration can be removed, for example a Fact Pattern, Field Constraint, other Conditional Element ("exists", "not exists", "from" etc) or an Action.

D : The "plus" icon ("+") allows you to add more patterns to the condition or the action part of the rule, or more attributes. In all cases, a popup option box is provided. For the "WHEN" part of the rule, you can choose from a list of Conditional Elements to add:

If you just put a fact (like is shown above) then all the patterns are combined together so they are all true ("and").

E : This shows the constraint for the "creditRating" field. Looking from left to right you find:-

F : This shows the constraint for the "applicationDate" field. Looking from left to right you find:

H : This shows an "action" of the rule, the Right Hand Side of a rule consists in a list of actions. In this case, we are updating the "explanation" field of the "LoanApplication" fact. There are quite a few other types of actions you can use:-


In the above example, you can see how to use a mixture of Conditional Elements, literal values, and formulas. The rule has 4 "top level" Patterns and 1 Action. The "top level" Patterns are:

  1. A Fact Pattern on Person. This Pattern contains two field constraints: one for birthDate field and the other one is a formula. Note that the value of the birthDate restriction is selected from a calendar. Another thing to note is that you can make calculations and use nested fields in the formula restriction (i.e. car.brand). Finally, we are setting a variable name ($p) to the Person Fact Type. You can then use this variable in other Patterns.

    Note

    The generated DRL from this Pattern will be:

    $p : Person( birthDate < "19-Dec-1982" , eval( car.brand == "Ford" && salary > (2500 * 4.1) ))
  2. A From Pattern. This condition will create a match for every Address whose street name is "Elm St." from the Person's list of addresses. The left side of the from is a regular Fact Pattern and the right side is an Expression Builder that let us inspect variable's fields.

    Note

    The generated DRL from this Pattern will be: Address( street == "Elm St." ) from $p.addresses

  3. A "Not Exist" Conditional Element. This condition will match when its content doesn't create a match. In this case, its content is a regular Fact Pattern (on Person). In this Fact Pattern you can see how variables ($p) could be used inside a formula value.

    Note

    The generated DRL from this Pattern will be: not Person( salary == ( $p.salary * 2 ) )

  4. A "From Accumulate" Conditional Element. This is maybe one of the most complex Patterns you can use. It consist in a Left Pattern (It must be a Fact Pattern. In this case is a Number Pattern. The Number is named $totalAddresses), a Source Pattern (Which could be a Fact Pattern, From, Collect or Accumulate conditional elements. In this case is an Address Pattern Restriction with a field restriction in its zip field) and a Formula Section where you can use any built-in or custom Accumulate Function (in this example a count() function is used). Basically, this Conditional Element will count the addresses having a zip code of 43240 from the Person's list of addresses.

    Note

    The generated DRL from this Pattern will be: $totalAddresses : Number() from accumulate ($a : Address( zipCode == " 43240") from $p.addresses, count($a))

The guided decision table feature allows decision tables to be edited in place on the web. This works similar to the guided editor by introspecting what facts and fields are available to guide the creation of a decision table. Rule attributes, meta-data, conditions and actions can be defined in a tabular format thus facilitating rapid entry of large sets of related rules. Web-based decision table rules are compiled into DRL like all other rule assets.

The guided decision table is split into two main sections:-


When a new empty decision table has been created you need to define columns for Facts, their constraints and corresponding actions.

Expand the "Decision table" element and you will see three further sections for "Conditions", "Actions" and "Options". Expanding either the "Conditions" or "Actions" sections reveals the "New column" icon. This can be used to add new column definitions to the corresponding section. Existing columns can be removed by clicking the "-" icon beside each column name, or edited by clicking the "pencil" icon also beside each column name. The "Options" section functions slightly differently however the principle is the same: clicking the "Add Attribute/Metadata" icon allows columns for table attributes to be defined (such as "salience", "no-loop" etc) or metadata added.


A Wizard can also be used to assist with defining the decision table columns.

The wizard can be chosen when first electing to create a new rule. The wizard provides a number of pages to define the table:-

The guided rule editor is great when you need to define a single rule, however if you need to define multiple rules following the same structure but with different values in field constraints or action sections a "Rule Template" is a valuable asset. Rule templates allow the user to define a rule structure with place-holders for values that are to be interpolated from a table of data. Literal values, formulae and expressions can also continue to be used.

Rule Templates can often be used as an alternative for Decision Tables in Drools Guvnor.

When you have completed the definition of your rule template you need to enter the data that will be used to interpolate the "Template Key" place-holders. Drools Guvnor provides the facility to enter data in a flexible grid within the guided editor screen. The grid editor can be launched by pressing the "Load Template Data" button on the guided editor screen.

The rule template data grid is very flexible; with different pop-up editors for the underlying fields' data-types. Columns can be resized and sorted; and cells can be merged and grouped to facilitate rapid data entry.

One row of data interpolates the "Template Key" place-holders for a single rule; thus one row becomes one rule.


For any rule base application, a fact model is needed to drive the rules. The fact model typically overlaps with the applications domain model, but in general it will be decoupled from it (as it makes the rules easier to manage over time). There are no technical limitations on using your domain model as your fact model, however this introduces tighter coupling between your business domain (domain model) and your knowledge domain (fact model). Consequentially if your domain model were to change you would need to, at the very least, revisit your rule definitions.

Why would you chose declared types over JAR files: generally this reinforces the fact that the model "belongs" to the KnowledgeBase, rather then the application, and allows the model to have a lifecycle separate from the application. It also allows Java types to be enriched with Rule specific annotations. Additionally it also removes the burden of keeping JAR files synchronised between rules and the applications that use the rules.

Declarative models can be either:-

Creating a Declarative Model is a two step process.

Once the Declarative Model asset has been created you are presented with the initial modelling screen; that is empty to begin.


Facts, being semantically equivalent to Java classes, can be created by selecting the "Add new fact type" button. An existing Fact definition can be edited by clicking the "pencil" icon on the same row as the Fact name. Furthermore existing Facts can be deleted by clicking the "[-]" icon.



Fact Fields can be created by selecting the "Add field" button. The type of a field is suggested by a list (but this list is not exhaustive). An existing Fact Field definition can be edited by clicking the "pencil" icon on the same row as the Fact Field name. Furthermore existing Fact Fields can be deleted by clicking the "[-]" icon.


Fact annotations can be created by selecting the "Add annotation" button. Annotations are listed under the Fact title, before the fields, by convention. Annotations are prefixed with the "@" symbol. This not only makes them instantly recognisable but is also consistent with their definition in DRL.

The annotation "Name" and "Value" are mandatory whereas the "Key" is optional. If a "Key" is not given a default value of "value" will be assigned. This is consistent with how annotations are held within Drools Expert.

An existing Fact Annotation can be edited by clicking the "pencil" icon on the same row as the Fact Annotation name. Furthermore existing Fact Annotations can be deleted by clicking the "[-]" icon.



Declarative types can extend existing:-



The DSL editor allows DSL Sentences to be authored. The reader should take time to explore DSL features in the Drools Expert documentation; as the syntax in Guvnor's DSL Editor is identical. The normal syntax is extended to provide "hints" to control how the DSL variable is rendered and validated within the user-interface.

The following "hints" are supported:-


Data enumerations are an optional asset type that technical folk can configure to provide drop down lists for the guided editor. These are stored and edited just like any other asset, and apply to the package that they belong to.

The contents of an enum config are a mapping of Fact.field to a list of values to be used in a drop down. That list can either be literal, or use a utility class (which you put on the classpath) to load a list of strings. The strings are either a value to be shown on a drop down, or a mapping from the code value (what ends up used in the rule) and a display value (see the example below, using the '=').


In the above diagram - the "MM" indicates a value that will be used in the rule, yet "Mini Mal" will be displayed in the GUI.

Getting data lists from external data sources: It is possible to have the Guvnor call a piece of code which will load a list of Strings. To do this, you will need a bit of code that returns a java.util.List (of String's) to be on the classpath of the Guvnor. Instead of specifying a list of values in the Guvnor itself - the code can return the list of Strings (you can use the "=" inside the strings if you want to use a different display value to the rule value, as normal). For example, in the 'Person.age' line above, you could change it to:

 'Person.age' : (new com.yourco.DataHelper()).getListOfAges()

This assumes you have a class called "DataHelper" which has a method "getListOfAges()" which returns a List of strings (and is on the classpath). You can of course mix these "dynamic" enumerations with fixed lists. You could for example load from a database using JDBC. The data enumerations are loaded the first time you use the guided editor in a session. If you have any guided editor sessions open - you will need to close and then open the rule to see the change. To check the enumeration is loaded - if you go to the Package configuration screen, you can "save and validate" the package - this will check it and provide any error feedback.

There are a few other advanced things you can do with data enumerations.

Drop down lists that depend on field values: Lets imagine a simple fact model, we have a class called Vehicle, which has 2 fields: "engineType" and "fuelType". We want to have a choice for the "engineType" of "Petrol" or "Diesel". Now, obviously the choice type for fuel must be dependent on the engine type (so for Petrol we have ULP and PULP, and for Diesel we have BIO and NORMAL). We can express this dependency in an enumeration as:

'Vehicle.engineType' : ['Petrol', 'Diesel']
'Vehicle.fuelType[engineType=Petrol]' : ['ULP', 'PULP' ]
'Vehicle.fuelType[engineType=Diesel]' : ['BIO', 'NORMAL' ]

This shows how it is possible to make the choices dependent on other field values. Note that once you pick the engineType, the choice list for the fuelType will be determined.

Loading enums programmatically: In some cases, people may want to load their enumeration data entirely from external data source (such as a relational database). To do this, you can implement a class that returns a Map. The key of the map is a string (which is the Fact.field name as shown above), and the value is a java.util.List of Strings.

public class SampleDataSource2 {


  public Map<String>, List<String> loadData() {
    Map data = new HashMap();
    List d = new ArrayList();
    d.add("value1");
    d.add("value2");
    data.put("Fact.field", d);
    return data;
 }
}

And in the enumeration in the BRMS, you put:

=(new SampleDataSource2()).loadData()

The "=" tells it to load the data by executing your code.

Mode advanced enumerations: In the above cases, the values in the lists are calculated up front. This is fine for relatively static data, or small amounts of data. Imagine a scenario where you have lists of countries, each country has a list of states, each state has a list of localities, each locality has a list of streets and so on... You can see how this is a lot of data, and it can not be loaded up. The lists should be loaded dependent on what country was selected etc...

Well the above can be addressed in the following fashion:

'Fact.field[dependentField1, dependentField2]' : '(new com.yourco.DataHelper()).getListOfAges("@{dependentField1}", "@{dependentField2}")'

Similar to above, but note that we have just specified what fields are needed, and also on the right of the ":" there are quotes around the expression. This expression will then be evaluated, only when needed, substituting the values from the fields specified. This means you can use the field values from the GUI to drive a database query, and drill down into data etc. When the drop down is loaded, or the rule loaded, it will refresh the list based on the fields. 'dependentField1' and 'dependentField2' are names of fields on the 'Fact' type - these are used to calculate the list of values which will be shown in a drop down if values for the "field".

Test Scenarios are used to validate that rules and knowledge base work as expected. When the knowledge base evolves, Test Scenarios guard against regression.


Given section lists the facts needed for the behaviour. Expect section lists the expected changes and actions done by the behaviour. Given facts are passed for the Test Scenario before execution. During the rule execution, changes in the knowledge base are recorded. After the execution ends the recorded actions, existing facts in the knowledge base and knowledge base output is compared against the expectations.


Change-set is one of the ways Drools has to group one or more Assets in a single Asset. Change-sets can then be added to a Knowledge Builder or a Knowledge Agent to process all the assets referenced by it.

By default, Guvnor provides a unique Change-Set per package containing the package binary or the drl source. The main problem with this is when you want to use just a sub-set of assets of a package (or even from different packages) in your application.

Using the Change-Set editor you can define your own change-sets inside Guvnor in any way you want. You could have a combination of different assets and packages, or even different snapshots of a package in a change-set. You can have all the change-sets per package you need, so if different applications are using the same package in different ways (different assets or assets' versions of a same package) you can make use of this feature of Guvnor.

Service Config is a special asset that defines an execution service configuration. This execution service is a war file (generated automatically by the editor) which you can deploy to execute KnowledgeBases remotely for any sort of client application. As this service is stateless, it is possible to have as many of these services deployed as you need to serve the client load.

This version of the execution server supports as many Knowledge Bases as you need, supporting also multiple stateless and stateful sessions in a native way.

To create a new Service you have to go to "Create New" -> "New Service Config" option in Knowledge Base section of Guvnor. In the following sections you have detailed information on how to configure your Service Config.



In the above configuration panel you have 6 items that you can interact with:

  1. Add Asset Button: add new assets to the tree using a wizard. See next section for further information.

  2. Remove Selected Button: remove the selected assets (the ones that are checked) from Assets Tree.

  3. Rename KBase Button: this button will open a standard “prompt for rename” dialog box.

  4. Advanced Options Button: opens the advanced knowledge base configuration dialog. Configurations that are not available in the panel, should be available in this advanced dialog. Detailed information about it can be found in the "Advanced Knowledge Base Configuration Options" section.

  5. Assets Tree: Here you have the complete set of assets, grouped by package and type, that are referenced by the active knowledge base configuration. For additional information, please read the "Assets Tree" section.

  6. Sessions Grid: Here users can create, delete and edit in place a list of desires ksessions. For detailed instructions on how to configure ksessions, please check the "Configuring Knowledge Sessions" section.


The ksessions grid is composed by the following columns:

  1. Add and Remove Icons: Users can use these icons to add new or remove existing knowledge sessions. Important to note that should exists at least one knowledge session.

  2. Knowledge Session Name: Defines the ksession name. Users can edit this particular field in place as highlighted on box "A".

  3. Session Type: Defines if a ksession is Stateless or Stateful. Users can also select the desired type directly on the grid.

  4. Configuration Button: This button opens the knowledge session configuration dialog. See next section for further information.

After configuring your knowledge bases and sessions, you're ready to download the service war. For so, all you need to do is click on the "Download War" button and the following screen (or a similar one, depending on your browser) will show up.


Warning

Before click on the "Download War" button, makes sure that you don't have pending changes. This is a very important step, once the the war file is generated based on the latest saved information and not on the current screen state.

The generated file is a ready to be deployed war file. Which mean that it contains all the necessary configuration files and all the needed dependencies as well. As dependency management is a crucial subject in a real world applications deployment, we will discuss that in more detail in the next section.

A scorecard is a graphical representation of a formula used to calculate an overall score. A scorecard can be used to predict the likelihood or probability of a certain outcome. Drools now supports additive scorecards. An additive scorecard calculates an overall score by adding all partial scores assigned to individual rule conditions.

Additionally, Drools Scorecards will allows for reason codes to be set, which help in identifying the specific rules (buckets) that have contributed to the overall score. Drools Scorecards will be based on the PMML 4.1 Standard.

The New Rule Wizard now allows for creation of scorecard assets.



The above image shows a scorecard with one characteristic. Each scorecard consists of two sections (a) Setup Parameters (b) Characteristic Section

The setup section consits of parameters that define the overall behaviour of this scorecard.

  1. Facts: This dropdown shows a list of facts that are visible in this package. These are classes that are imported into this package.

  2. Resultant Score Field: Shows a list of fields from the selected fact. Only fields of type 'double' are shown. If this dropdown is empty double check your fact model. The final calculated score will be stored in this field.

  3. Initial Score: Numeric Text Field to capture the initial score. The generated rules will initialize the 'Resultant Score Field' with this score and then is added to the overall score whenever partial scores are summed up.

  4. Use Reason Codes: Boolean indicator to compute reason codes along with the final score. Selecting Yes/No in this field will enable/disable the 'Resultant Reason Codes Field', 'Reason Code Algorithm' and the 'Baseline Score' field.

  5. Resultant Reason Codes Field: Shows a list of fields from the selected fact. Only fields of type 'java.util.List' are shown. This collection will hold the reason codes selected by this scorecard.

  6. Reason Code Algorithm: May be "none", "pointsAbove" or "pointsBelow", describing how reason codes shall be ranked, relative to the baseline score of each Characteristic, or as set at the top-level scorecard.

  7. Baseline Score: A single value to use as the baseline comparison score for all characteristics, when determining reason code ranking. Alternatively, unique baseline scores may be set for each individual Characteristic as shown below. This value is required only when UseReasonCodes is "true" and baselineScore is not given for each Characteristic.

On Clicking the 'New Characteristic' button, a new empty characteristic editor is added to the scorecard. Defines the point allocation strategy for each scorecard characteristic (numeric or categorical). Each scorecard characteristic is assigned a single partial score which is used to compute the overall score. The overall score is simply the sum of all partial scores. Partial scores are assumed to be continuous values of type "double".

On Clicking the 'New Attribute' button, a new empty attribute editor. In scorecard models, all the elements defining the Attributes for a particular Characteristic must all reference a single field.


  1. Operator: The condition upon which the mapping between input attribute and partial score takes place. The operator dropdown will show different values depending on the datatype of the selected Field.

    1. DataType Strings: "=", "in".

    2. DataType Integers: "=", ">", "<", ">=", "<=", ">..<", ">=..<", ">=..<=", ">..<=".

    3. DataType Boolean: "true", "false".

    Refer to the next sub-section (values) for more details.

  2. Value: Basis the operator selected the value specified can either be a single value or a set of values separated by comma (","). The value field is disabled for operator type boolean.

    Table 4.1. Operators / Values
    Data Type Operator Value Remarks
    String = Single Value will look for an exact match
    String in Comma Separated Values (a,b,c,...) The operator 'in' indicates an evaluation to TRUE if the field value is contained in the comma separated list of values
    Boolean is true N/A Value Field is uneditable (readonly)
    Boolean is false N/A Value Field is uneditable (readonly)
    Numeric = Single Value Equals Operator
    Numeric > Single Value Greator Than Operator
    Numeric < Single Value Less Than Operator
    Numeric >= Single Value Greater than or equal To
    Numeric <= Single Value Less than or equal To
    Numeric >..< Comma Separated Values (a,b) (Greater than Value 'a') and (less than value 'b')
    Numeric >=..< Comma Separated Values (a,b) (Greater than or equal to Value 'a') and (less than value 'b')
    Numeric >=..<= Comma Separated Values (a,b) (Greater than or equal to Value 'a') and (less than or equal to value 'b')
    Numeric >..<= Comma Separated Values (a,b) (Greater than Value 'a') and (less than or equal to value 'b')
  3. Partial Score: Defines the score points awarded to the Attribute.

  4. Reason Code: Defines the attribute's reason code. If the reasonCode attribute is used in this level, it takes precedence over the ReasonCode associated with the Characteristic element.

  5. Actions: Delete this attribute. Prompts the user for confirmation.

Note

If Use Reason Codes is "true", then Baseline Score must be defined at the Scorecard level or for each Characteristic, and Reason Code must be provided for each Characteristic or for each of its input Attributes. If Use Reason Codes is "false", then BaselineScore and ReasonCode are not required.

The two main ways of viewing the repository are by using the Package Explorer or user-driven Categorization (tagging) as outlined previously.

The Package Explorer appears in the "Knowledge Bases" section of the left-hand side navigation bar. The Package Explorer shows a list of all packages (other than those that have been archived).

The list of packages can either be viewed hierarchically or flat and fully expanded or collapsed using the icons below the tree-view.



Clicking on a package name in the tree-view will launch the Asset Viewer.

Package analysis uses Drools rules to statically analyse knowledge modules. It produces a report that contains information about the quality of the knowledge module.

Package analysis message types:


Categories allow rules (assets) to be labeled (or tagged) with any number of categories that you define. This means that you can then view a list of rules that match a specific category. Rules can belong to any number of categories. In the above diagram, you can see this can in effect create a folder/explorer like view of assets. The names can be anything you want, and are defined by the Guvnor administrator (you can also remove/add new categories - you can only remove them if they are not currently in use).

Generally categories are created with meaningful name that match the area of the business the rule applies to (if the rule applies to multiple areas, multiple categories can be attached). Categories can also be used to "tag" rules as part of their life-cycle, for example to mark as "Draft" or "For Review".


The view above shows the category editor/viewer that is seen when you open an asset. In this example you can see the asset belongs to 2 categories, with a "+" button to add additional items (use the trash can item to remove them). This means that when either category is used to show a list of assets, you will see that asset.

In the above example, the first Category "Finance" is a "top level" category. The second one: "HR/Awards/QAS" is a still a single category, but its a nested category: Categories are hierarchical. This means there is a category called "HR", which contains a category "Awards" (it will in fact have more sub-categories of course), and "Awards" has a sub-category of QAS. The screen shows this as "HR/Awards/QAS" - its very much like a folder structure you would have on your hard disk (the notable exception is of course that rules can appear in multiple places).

When you open an asset to view or edit, it will show a list of categories that it currently belongs to If you make a change (remove or add a category) you will need to save the asset - this will create a new item in the version history. Changing the categories of a rule has no effect on its execution.


The above view shows the administration screen for setting up categories (there) are no categories in the system by default. As the categories can be hierarchical you chose the "parent" category that you want to create a sub-category for. From here categories can also be removed (but only if they are not in use by any current versions of assets).

As a general rule, an asset should only belong to 1 or 2 categories at a time. Categories are critical in cases where you have large numbers of rules. The hierarchies do not need to be too deep, but should be able to see how this can help you break down rules/assets into manageable chunks. Its ok if its not clear at first, you are free to change categories as you go.

This part covers Guvnor for software developers.

Its all very interesting to manage rules, but how to you use or "consume" them in your application? This section covers the usage of the KnowledgeAgent deployment component that automates most of this for you.

The knowledge agent is a component which is embedded in knowledge-api. To use this, you don't need any extra components. In fact, if you are using Guvnor, your application should only need to include the knowledge-api and drools-core dependencies in its classpath (drools and mvel JARs only), and no other rules specific dependencies.

Note that there is also a drools-ant ant task, so you can build rules as part of an Ant script (for example in cases where the rules are edited in the IDE) without using Guvnor at all - the drools-ant task will generate .pkg files the same as Guvnor.

Once you have "built" your rules in a package in Guvnor (or from the ant task), you are ready to use the agent in your target application.

The Following example constructs an agent that will build a new KnowledgeBase from the files specified in the path String. It will poll those files every 60 seconds, which is the default, to see if they are updated. If new files are found it will construct a new KnowledgeBase. If the change set specifies a resource that is a directory it's contents will be scanned for changes too.

KnowledgeAgent kagent = KnowledgeAgentFactory.newKnowledgeAgent( "MyAgent" );

kagent.applyChangeSet( ResourceFactory.newUrlResource( url ) );
KnowledgeBase kbase = kagent.getKnowledgeBase();

The KnowledgeAgent can accept a configuration that allows for some of the defaults to be changed. An example property is drools.agent.scanDirectories, by default any specified directories are scanned for new additions, it is possible to disable this.

KnowledgeBase kbase = KnowledgeBaseFactory.newKnowledgeBase();

KnowledgeAgentConfiguration kaconf = KnowledgeAgentFactory.newKnowledgeAgentConfiguration();
// we do not want to scan directories, just files
kaconf.setProperty( "drools.agent.scanDirectories", "false" ); 
// the name of the agent
KnowledgeAgent kagent = KnowledgeAgentFactory.newKnowledgeAgent( "test agent", kaconf );
// resource to the change-set xml for the resources to add                                                                  
kagent.applyChangeSet( ResourceFactory.newUrlResource( url ) ); 

An example of the change-set.xml file.


<?xml version="1.0" encoding="UTF-8"?>
<change-set xmlns="http://drools.org/drools-5.0/change-set"
            xmlns:xs="http://www.w3.org/2001/XMLSchema-instance"
            xs:schemaLocation="http://drools.org/drools-5.0/change-set http://anonsvn.jboss.org/repos/labs/labs/jbossrules/trunk/drools-api/src/main/resources/change-set-1.0.0.xsd" >
    <add>
      <resource source="http://localhost:8080/guvnor-5.5.0.Final/org.drools.guvnor.Guvnor/package/mortgages/LATEST" type="PKG" basicAuthentication="enabled" username="uid" password="pwd"/>
    </add> 
</change-set>

Resource scanning is not on by default, it's a service and must be started, the same is for notification. This can be done via the ResourceFactory.

ResourceFactory.getResourceChangeNotifierService().start();

ResourceFactory.getResourceChangeScannerService().start();

Following shows the deployment screen of Guvnor, which provides URLs and downloads of packages.


You can see the "Package URI" - this is the URL that you would copy and paste into the change-set.xml file to specify that you want this package. It specifies an exact version (in this case to a snapshot) - each snapshot has its own URL. If you want the latest snapshot, replace the name of the snapshot in the URL with the word "LATEST".

You can also download a .pkg file from here, which you can drop in a directory and use the "file" or "dir" feature of the KnowledgeAgent if needed (in some cases people will not want to have the runtime automatically contact Guvnor for updates - but that is generally the easiest way for many people).

The repository back end can also be accessed via Rest. Rest is a http based protocol API, which has clients on all platforms and in all programming languages.

Representational State Transfer (REST) is a style of software architecture for distributed hypermedia systems such as the World Wide Web. The term Representational State Transfer was introduced and defined in 2000 by Roy Fielding in his doctoral dissertation.

REST-style architectures consist of clients and servers. Clients initiate requests to servers; servers process requests and return appropriate responses. Requests and responses are built around the transfer of representations of resources. A resource can be essentially any coherent and meaningful concept that may be addressed. A representation of a resource is typically a document that captures the current or intended state of a resource. The REST protocol is often considered as a light protocol versus SOAP.

The Guvnor Rest API is divided in two groups of services : one around accessing rule assets by their names and packages and the second accessing rule assets by categories.

A rule asset represents any element that can be stored and handled in Guvnor : a guided rule, a web decision table, a test scenario, etc.

The http address to use as base address is http://{ServerName}/{httpPort}/{guvnorWarFilename}/rest where ServerName is the host name on the server on which Guvnor is deployed, httpPort the port number (8080 by default development) and guvnorWarFilename the name of the archived deployed (guvnor-webapp-5.3.0 for version 5.3.0) without the extension.

Use the URLs listed below to access rules assets by package. The examples below assume a base URL of http://localhost:8080/guvnor-5.5.0.Final/rest/.

/packages

http://localhost:8080/guvnor-5.5.0.Final/rest/packages

The GET method produces MIME-Types:

  • application/atom+XML

  • application/json

  • application/xml

The GET method return all packages contained in the repository in the requested format (Atom feed, JSON, or XML).

The POST method produces MIME-Types:

  • application/atom+XML

  • application/json

  • application/xml

The POST method consumes MIME-Types:

  • application/octet-stream

  • application/atom+xml

  • application/json

  • application/xml

The POST method creates a new package from an input stream of DRL, an Atom feed, JSON, or XML, and returns the newly created package in the requested format (Atom feed, JSON, or XML).

/packages/{packageName}

http://localhost:8080/guvnor-5.5.0.Final/rest/packages/{packageName}

The GET method produces MIME-Types:

  • application/atom+xml

  • application/json

  • application/xml

The GET method returns the metadata of the package {packageName} as an Atom entry when the MIME-Type is application/atom+xml, and as a package element when the MIME-Type is application/json or application/xml.

The PUT method produces MIME-Types:

  • application/atom+xml

  • application/json

  • application/xml

The PUT method updates the metadata of package {packageName} with the provided format (Atom Entry, JSON, or XML).

The DELETE method deletes package {packageName}.

/packages/{packageName}/source

http://localhost:8080/guvnor-5.5.0.Final/rest/packages/{packageName}/source

The GET method produces MIME-Types:

  • text/plain

The GET method returns the source code of the package {packageName} as a text file.

/packages/{packageName}/binary

http://localhost:8080/guvnor-5.5.0.Final/rest/packages/{packageName}/binary

The GET method produces MIME-Types:

  • application/octet-stream

The GET method returns the compiled binary of the package {packageName} as a binary stream. If the package has not been compiled yet or its binary is not up to date, this will compile the package first.

/packages/{packageName}/versions

http://localhost:8080/guvnor-5.5.0.Final/rest/packages/{packageName}/versions

The GET method produces MIME-Types:

  • application/atom+xml

The GET method returns the list of package {packageName} versions as an Atom Feed.

/packages/{packageName}/versions/{version}

http://localhost:8080/guvnor-5.5.0.Final/rest/packages/{packageName}/versions/{version}

The GET method produces MIME-Types:

  • application/atom+xml

The GET method returns the metadata of package {packageName} and of version {version} as an Atom Entry.

/packages/{packageName}/versions/{version}/source

http://localhost:8080/guvnor-5.5.0.Final/rest/packages{packageName}/versions/{version}/source

The GET method produces MIME-Types:

  • text/plain

The GET method returns the source code of package {packageName} and of version {version} as a text file.

/packages/{packageName}/versions/{version}/binary

http://localhost:8080/guvnor-5.5.0.Final/rest/packages/{packageName}/versions/{version}/binary

The GET method produces MIME-Types:

  • application/octet-stream

The GET method returns the binary (compiled code) of package {packageName} and of version {version} as an octet stream. If the package version has not been built, it returns HTTP code 500 with an error message.

/packages/{packageName}/assets

http://localhost:8080/guvnor-5.5.0.Final/rest/packages{packageName}/assets

The GET method produces MIME-Types:

  • application/atom+xml

  • application/json

  • application/xml

The GET method returns the list of rule assets contained in package {packageName} in the requested format (Atom feed, JSON, or XML).

The POST method produces MIME-Types:

  • application/atom+xml

  • application/octet-stream

The POST method creates an asset in package {packageName}.

When an Atom Entry is provided the following information must be included in the input: asset name, asset description, asset initial category, and asset format.

When an octet-stream is provided the value of slug header is used to indicate the name of the asset. If the slug header is missing a HTTP 500 error is returned.

The POST method produces MIME-Types:

  • application/json

  • application/xml

The POST method consumes MIME-Types:

  • multipart/form-data

The POST method creates the asset {assetName} for the package {packageName}.

/packages/{packageName}/assets/{assetName}

http://localhost:8080/guvnor-5.5.0.Final/rest/packages{packageName}/assets/{assetName}

The GET method produces MIME-Types:

  • application/atom+xml

  • application/json

  • application/xml

The GET method returns the rule asset {assetName} contained in package {packageName} in the requested format (Atom feed, JSON, or XML).

The PUT method produces MIME-Types:

  • application/atom+xml

  • application/json

  • application/xml

The PUT method consumes MIME-Types:

  • multipart/form-data

The PUT method updates the metadata of the rule asset {assetName} contained in package {packageName} with the provided format (Atom Entry, JSON, or XML). When Multipart/form-data is supplied the asset {assetName} in package {packageName} is updated.

The DELETE method deletes the rule asset {assetName} contained in package {packageName}.

/packages/{packageName}/assets/{assetName}/binary

http://localhost:8080/guvnor-5.5.0.Final/rest/packages{packageName}/assets/{assetName}/binary

The GET method produces MIME-Types:

  • application/octet-stream

The GET method returns the binary content of rule asset {assetName} contained in package {packageName}. If this asset has no binary content, the source content is returned instead.

The PUT method produces MIME-Types:

  • application/octet-stream

The PUT method updates the binary content of the rule asset {assetName} contained in package {packageName}.

/packages/{packageName}/assets/{assetName}/source

http://localhost:8080/guvnor-5.5.0.Final/rest/packages{packageName}/assets/{assetName}/source

The GET method produces MIME-Types:

  • plain/text

The GET method returns the content of rule asset {assetName} contained in package {packageName}. If this is a binary asset, the binary data is returned as a byte array.

The PUT method produces MIME-Types:

  • plain/text

The PUT method updates the source code of the rule asset {assetName} contained in package {packageName}.

/packages/{packageName}/assets/{assetName}/versions

http://localhost:8080/guvnor-5.5.0.Final/rest/packages{packageName}/assets/{assetName}/versions

The GET method produces MIME-Types:

  • application/atom+xml

The GET method returns the list of rule asset {assetName} versions contained in package {packageName} as an Atom Feed.

/packages/{packageName}/assets/{assetName}/versions/{version}

http://localhost:8080/guvnor-5.5.0.Final/rest/packages{packageName}/assets/{assetName}/versions/{version}

The GET method produces MIME-Types:

  • application/atom+xml

The GET method returns the metadata of rule asset {assetName} of version {version} contained in package {packageName} as an Atom Entry.

/packages/{packageName}/assets/{assetName}/versions/{version}/source

http://localhost:8080/guvnor-5.5.0.Final/rest/packages{packageName}/assets/{assetName}/versions/{version}/source

The GET method produces MIME-Types:

  • plain/text

The GET method returns the source code of rule asset {assetName} of version {version} contained in package {packageName} as a text file.

/packages/{packageName}/assets/{assetName}/versions/{version}/binary

http://localhost:8080/guvnor-5.5.0.Final/rest/packages{packageName}/assets/{assetName}/versions/{version}/binary

The GET method produces MIME-Types:

  • application/octet-stream

The GET method returns the binary content of rule asset {assetName} of version {version} contained in package {packageName}. If this asset has no binary content, the source content is returned instead.

/packages/{packageName}/snapshot/{snapshotName}

http://localhost:8080/guvnor-5.5.0.Final/rest/packages{packageName}/snapshot/{snapshotName}

The POST method creates a snapshot {snapshotName} for the package {packageName}.



Use the URLs listed below to access rules assets by category. The examples below assume a base URL of http://localhost:8080/guvnor-5.5.0.Final/rest/

/categories/

http://localhost:8080/guvnor-5.5.0.Final/rest/categories

The GET method produces MIME-Types:

  • application/json

  • application/xml

The GET method lists all categories.

/categories/{categoryPath}

http://localhost:8080/guvnor-5.5.0.Final/rest/categories/{categoryPath}

The GET method produces MIME-Types:

  • application/json

  • application/xml

The GET method returns information for a single category.

The PUT method creates a new category with the supplied category path {categoryPath}.

The DELETE method deletes the category with the supplied category path {categoryPath}.

/categories/{categoryPath}/children

http://localhost:8080/guvnor-5.5.0.Final/rest/categories/{categoryPath}/children

The GET method produces MIME-Types:

  • application/json

  • application/xml

The GET method lists all subcategories under the provided category {categoryPath}.

/categories/{categoryPath}/assets

http://localhost:8080/guvnor-5.5.0.Final/rest/categories/{categoryPath}/assets

The GET method produces MIME-Types:

  • application/atom+xml

  • application/json

  • application/xml

The GET method returns an Atom feed to all the rule assets that the listed category {category} when the MIME-type is application/atom+xml, and returns a list of asset objects representing rule assets that have the category {categoryPath} when the MIME-Type is either application/json or application/xml.

/categories/{categoryPath}/assets/page/{page}

http://localhost:8080/guvnor-5.5.0.Final/rest/categories/{categoryPath}/assets/page/{page}

The GET method produces MIME-Types:

  • application/json

  • application/xml

The GET method returns a list of asset objects representing rules assets that have the listed category {categoryPath} and retrieves page {page}, which is a numeric value starting at 1. A page contains 10 elements. If the list contains 20 elements then the list will have 2 pages. Page 1 must be called before page 2 and so on.

We are giving a list of examples to help using the Guvnor's Rest API

We are using apache CXF in our example to show how to access the Rest API of Guvnor. In the example here we are getting and updating a web decision table. But this example applies to all Guvnor asset type.


In the first line of code above, we are first creating a WebClient variable that points to the server (here on localhost on port 8080).

In the second line of code above, we are retrieving the source content by accessing the /rest/packages/{packageName}/assets/{assetName}/source, where in our case packageName is "essaiRest" and assetName is "tab2".

In the third line of code above, the source code we get is the data structure of a Web decision table. So to be able to manipulate the Web decision table, we have to transform the string variable (the source code that contains the xml of the data structure of the web decision table) in the java structure (a java class) for web decision table GuidedDecisionTable52. All guided asset in Guvnor have a java structure to manipulate them


In the first line of code above, we are first creating a java String variable that contains the authorization element needed to update an asset in the Guvnor repository.

In the next lines of code above, we are doing some stuff to modify the Web decision table.

In the following lines of code above, we are first transforming the java structure in an xml structure that we put in a java String variable. Then we again create a WebClient but this time we are also filling the header with a variable "Authorization" that contains the String we built in the first line and that contains the user name "guest" and its password (here no password). We then put the new content on the Guvnor repository.

Next you can find the pom.xml file to use the Guvnor Rest API in case you are using Maven.


In this example we are using Apache Abdera to help parsing and creating Atom Entry and Feed.

Example 9.4. Retrieving all packages contained in the Guvnor repository in Atom Feed format



    public void testGetPackagesForAtom() throws MalformedURLException, IOException {
        URL url = new URL("http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages");
        HttpURLConnection connection = (HttpURLConnection)url.openConnection();
        connection.setRequestProperty("Authorization",
                "Basic " + new Base64().encodeToString(( "admin:admin".getBytes() )));
        connection.setRequestMethod("GET");
        connection.setRequestProperty("Accept", MediaType.APPLICATION_ATOM_XML);
        connection.connect();
        //System.out.println(IOUtils.toString(connection.getInputStream()));
        InputStream in = connection.getInputStream();
        Document<Feed> doc = abdera.getParser().parse(in);
        Feed feed = doc.getRoot();
        System.out.println("BaseUriPath: " + feed.getBaseUri().getPath());
        System.out.println("Title: " + feed.getTitle());
        Iterator<Entry> it = feed.getEntries().iterator();
        while (it.hasNext()) {
            Entry entry = it.next();
            System.out.println("Title: " + entry.getTitle());
            List<Link> links = entry.getLinks();
            System.out.println("Href: " + links.get(0).getHref().getPath());
        }
    }


The client can navigate to specific packages using the package URL retrieved from package list.

Example 9.6. Retrieving the metadata of the specified package as an Atom Entry

    public void testGetPackageForAtom() throws MalformedURLException, IOException {

        URL url = new URL("http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages");
        HttpURLConnection connection = (HttpURLConnection)url.openConnection();
        connection.setRequestProperty("Authorization",
                "Basic " + new Base64().encodeToString(( "admin:admin".getBytes() )));
        connection.setRequestMethod("GET");
        connection.setRequestProperty("Accept", MediaType.APPLICATION_ATOM_XML);
        InputStream in = connection.getInputStream();
        //System.out.println(IOUtils.toString(connection.getInputStream()));
        
        Document<Entry> doc = abdera.getParser().parse(in);
        Entry entry = doc.getRoot();
        System.out.println("BaseUri: " + entry.getBaseUri().getPath());
        System.out.println("Title: " + entry.getTitle());
        System.out.println("Published: " + entry.getPublished());
        System.out.println("Author: " + entry.getAuthor().getName());
        System.out.println("Summary: " + entry.getSummary());
        System.out.println("ContentSrcPath: " + entry.getContentSrc().getPath());
        List<Link> links = entry.getLinks();
        Map<String, Link> linksMap = new HashMap<String, Link>();
        for(Link link : links){
            System.out.println("Link Title: " + link.getTitle());
            System.out.println("Link Path: " + link.getHref().getPath());
            linksMap.put(link.getTitle(), link);
        }
        ExtensibleElement metadataExtension  = entry.getExtension(Translator.METADATA);
        ExtensibleElement archivedExtension = metadataExtension.getExtension(Translator.ARCHIVED);
        System.out.println("ARCHIVED: " + archivedExtension.getSimpleExtension(Translator.VALUE));
        ExtensibleElement uuidExtension = metadataExtension.getExtension(Translator.UUID);
        System.out.println("UUID: " + uuidExtension.getSimpleExtension(Translator.VALUE));
        ExtensibleElement checkinCommentExtension = metadataExtension.getExtension(Translator.CHECKIN_COMMENT);
        System.out.println("CHECKIN_COMMENT: " + checkinCommentExtension.getSimpleExtension(Translator.VALUE));
        ExtensibleElement versionNumberExtension = metadataExtension.getExtension(Translator.VERSION_NUMBER);
        System.out.println("VERSION_NUMBER: " + versionNumberExtension.getSimpleExtension(Translator.VALUE));
    }
    

Example 9.7. Sample message returned from server


<entry xmlns="http://www.w3.org/2005/Atom"
  xml:base="http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages">
  <title type="text">mortgages</title>
  <summary type="text">Mortgages that aren't stupid</summary>
  <published>2011-05-02T09:16:16.246Z</published>
  <author>
    <name>mic</name>
  </author>
  <id>http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages
  </id>
  <link
    href="http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages/assets/drools"
    title="drools" rel="asset" />
  <link
    href="http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages/assets/MortgageModel"
    title="MortgageModel" rel="asset" />
  <link
    href="http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages/assets/Underage"
    title="Underage" rel="asset" />
  <link
    href="http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages/assets/Are%20they%20old%20enough"
    title="Are they old enough" rel="asset" />
  <link
    href="http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages/assets/No%20bankruptcies"
    title="No bankruptcies" rel="asset" />
  <link
    href="http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages/assets/Bankruptcies"
    title="Bankruptcies" rel="asset" />
  <link
    href="http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages/assets/Bankruptcy%20history"
    title="Bankruptcy history" rel="asset" />
  <link
    href="http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages/assets/credit%20ratings"
    title="credit ratings" rel="asset" />
  <link
    href="http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages/assets/No%20bad%20credit%20checks"
    title="No bad credit checks" rel="asset" />
  <link
    href="http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages/assets/Good%20credit%20history%20only"
    title="Good credit history only" rel="asset" />
  <link
    href="http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages/assets/no%20NINJAs"
    title="no NINJAs" rel="asset" />
  <link
    href="http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages/assets/NINJAs"
    title="NINJAs" rel="asset" />
  <link
    href="http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages/assets/Pricing%20loans"
    title="Pricing loans" rel="asset" />
  <link
    href="http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages/assets/Pricing%20low%20end"
    title="Pricing low end" rel="asset" />
  <link
    href="http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages/assets/Unapprove%20by%20default"
    title="Unapprove by default" rel="asset" />
  <link
    href="http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages/assets/Dummy%20rule"
    title="Dummy rule" rel="asset" />
  <link
    href="http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages/assets/ApplicantDsl"
    title="ApplicantDsl" rel="asset" />
  <link
    href="http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages/assets/CreditScoreApproval"
    title="CreditScoreApproval" rel="asset" />
  <link
    href="http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages/assets/CreditApproval"
    title="CreditApproval" rel="asset" />
  <link
    href="http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages/assets/DateDslRule"
    title="DateDslRule" rel="asset" />
  <link
    href="http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages/assets/RegexDslRule"
    title="RegexDslRule" rel="asset" />
  <link
    href="http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages/assets/DSLWithDate"
    title="DSLWithDate" rel="asset" />
  <link
    href="http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages/assets/myws"
    title="myws" rel="asset" />
  <metadata xmlns="">
    <archived>
      <value>false</value>
    </archived>
    <uuid>
      <value>da98caef-e1c4-4f98-880c-46a740c9131f</value>
    </uuid>
    <state>
      <value></value>
    </state>
    <versionNumber>
      <value>2</value>
    </versionNumber>
    <checkinComment>
      <value>Mortgages that aren't stupid</value>
    </checkinComment>
  </metadata>
  <content src="http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages/binary" />
</entry>



Retrieving package metadata with specified version as an Atom Entry.

Example 9.12. Retrieving package metadata with specified version as an Atom Entry



    public void testGetHistoricalPackageForAtom() throws MalformedURLException, IOException {
        URL url = new URL("http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages/versions/5");
        HttpURLConnection connection = (HttpURLConnection)url.openConnection();
        connection.setRequestProperty("Authorization",
                "Basic " + new Base64().encodeToString(( "admin:admin".getBytes() )));
        connection.setRequestMethod("GET");
        connection.setRequestProperty("Accept", MediaType.APPLICATION_ATOM_XML);
        connection.connect();
        //System.out.println(IOUtils.toString(connection.getInputStream()));
        InputStream in = connection.getInputStream();
        Document<Entry> doc = abdera.getParser().parse(in);
        Entry entry = doc.getRoot();
        System.out.println("BaseUri: " +  entry.getBaseUri().getPath());
        System.out.println("Title: " + entry.getTitle());
        System.out.println("Summary: " +  entry.getSummary());
        System.out.println("ContentSrc: " +  entry.getContentSrc().getPath());
        List<Link> links = entry.getLinks();
        Map<String, Link> linksMap = new HashMap<String, Link>();
        for(Link link : links){
            System.out.println("Link Title: " + link.getTitle());
            System.out.println("Link Path: " + link.getHref().getPath());
            linksMap.put(link.getTitle(), link);
        }
        ExtensibleElement metadataExtension  = entry.getExtension(Translator.METADATA);
        ExtensibleElement archivedExtension = metadataExtension.getExtension(Translator.ARCHIVED);
        System.out.println("ARCHIVED: " + archivedExtension.getSimpleExtension(Translator.VALUE));
        ExtensibleElement uuidExtension = metadataExtension.getExtension(Translator.UUID);
        System.out.println("UUID: " + uuidExtension.getSimpleExtension(Translator.VALUE));
        ExtensibleElement checkinCommentExtension = metadataExtension.getExtension(Translator.CHECKIN_COMMENT);
        System.out.println("CHECKIN_COMMENT: " + checkinCommentExtension.getSimpleExtension(Translator.VALUE));
        ExtensibleElement versionNumberExtension = metadataExtension.getExtension(Translator.VERSION_NUMBER);
        System.out.println("VERSION_NUMBER: " + versionNumberExtension.getSimpleExtension(Translator.VALUE));
    }

Example 9.13. Sample message returned from server


<entry xmlns="http://www.w3.org/2005/Atom"
  xml:base="http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages/versions/5">
  <title type="text">mortgages</title>
  <summary type="text">update package description</summary>
  <published>2012-04-26T09:36:11.588Z</published>
  <author>
    <name>admin</name>
  </author>
  <id>http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages/versions/5
  </id>
  <link
    href="http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages/versions/5/assets/drools"
    title="drools" rel="asset" />
  <link
    href="http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages/versions/5/assets/MortgageModel"
    title="MortgageModel" rel="asset" />
  <link
    href="http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages/versions/5/assets/Underage"
    title="Underage" rel="asset" />
  <link
    href="http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages/versions/5/assets/Are%20they%20old%20enough"
    title="Are they old enough" rel="asset" />
  <link
    href="http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages/versions/5/assets/No%20bankruptcies"
    title="No bankruptcies" rel="asset" />
  <link
    href="http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages/versions/5/assets/Bankruptcies"
    title="Bankruptcies" rel="asset" />
  <link
    href="http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages/versions/5/assets/Bankruptcy%20history"
    title="Bankruptcy history" rel="asset" />
  <link
    href="http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages/versions/5/assets/credit%20ratings"
    title="credit ratings" rel="asset" />
  <link
    href="http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages/versions/5/assets/No%20bad%20credit%20checks"
    title="No bad credit checks" rel="asset" />
  <link
    href="http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages/versions/5/assets/Good%20credit%20history%20only"
    title="Good credit history only" rel="asset" />
  <link
    href="http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages/versions/5/assets/no%20NINJAs"
    title="no NINJAs" rel="asset" />
  <link
    href="http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages/versions/5/assets/NINJAs"
    title="NINJAs" rel="asset" />
  <link
    href="http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages/versions/5/assets/Pricing%20loans"
    title="Pricing loans" rel="asset" />
  <link
    href="http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages/versions/5/assets/Pricing%20low%20end"
    title="Pricing low end" rel="asset" />
  <link
    href="http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages/versions/5/assets/Unapprove%20by%20default"
    title="Unapprove by default" rel="asset" />
  <link
    href="http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages/versions/5/assets/Dummy%20rule"
    title="Dummy rule" rel="asset" />
  <link
    href="http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages/versions/5/assets/ApplicantDsl"
    title="ApplicantDsl" rel="asset" />
  <link
    href="http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages/versions/5/assets/CreditScoreApproval"
    title="CreditScoreApproval" rel="asset" />
  <link
    href="http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages/versions/5/assets/CreditApproval"
    title="CreditApproval" rel="asset" />
  <link
    href="http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages/versions/5/assets/DateDslRule"
    title="DateDslRule" rel="asset" />
  <link
    href="http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages/versions/5/assets/RegexDslRule"
    title="RegexDslRule" rel="asset" />
  <link
    href="http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages/versions/5/assets/DSLWithDate"
    title="DSLWithDate" rel="asset" />
  <link
    href="http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages/versions/5/assets/myws"
    title="myws" rel="asset" />
  <metadata xmlns="">
    <archived>
      <value>false</value>
    </archived>
    <uuid>
      <value>8c4ed0f7-a034-4411-98ed-3e7fc3af994a</value>
    </uuid>
    <state>
      <value></value>
    </state>
    <versionNumber>
      <value>5</value>
    </versionNumber>
    <checkinComment>
      <value>update package description</value>
    </checkinComment>
  </metadata>
  <content
    src="http://127.0.0.1:8080/guvnor-5.4.0-SNAPSHOT-jboss-as-7.0/rest/packages/mortgages/versions/5/binary" />
</entry>

The Eclipse Guvnor tools (EGT) provide the ability to push/pull artifacts from the Guvnor repository server and the developers workspace in eclipse. It is therefore possible for artifacts to be both managed via Guvnor as well as in traditional developer friendly SCM systems (such as subversion). The Guvnor repository is not intended as a Source Code Management (SCM) solution, and the EGT are not intended to be Eclipse “team provider” extensions or replacements. Rather, the Guvnor repository is a location where certain artifacts (such as rules and SOA policy definitions) are controlled (“governed”) by policies defined by the deployment environment. The purpose of the EGT is then to enable access to resources held by the Guvnor repository, so they can be used in development. Thus, limited capabilities for reading, writing, adding, and removing Guvnor repository resources are provided in the EGT.

The source code for the EGT is available in github. EGT consist of two plug-ins: org.guvnor.tools and org.eclipse.webdav. They require Eclipse 3.3.x. The current Eclipse Drools plug-ins are also useful for viewing Guvnor repository resources such as rule definitions, but not required for operation of the EGT.

After opening the Guvnor perspective, the first task is to make a connection to a Guvnor repository. This is handled by the Guvnor Connection wizard. This wizard appears in a number of places within the EGT (as detailed below), but in this section we will cover only the two most basic entry points. The Guvnor Connection wizard can be started using the Eclipse menu: File , New , Other , Guvnor , Guvnor repository location, or in the Guvnor Explorer using the drop-down menu:


or the menu button:


Choosing either of these will start the Guvnor connection wizard:


Default values appear in the Location, Port, and Repository fields. (See "Guvnor plugin Preferences" for details about how to change these default values.) Of course, any of these fields can be edited by typing in the corresponding text box. Drag-and-drop or paste into the Location field of a typical Guvnor repository URL such as http://localhost:8080/guvnor-5.5.0.Final/org.drools.guvnor.Guvnor/webdav results in the URL being parsed into the respective fields as well. The authentication information (user name and password) can optionally be stored in the Eclipse workbench's key-ring file based on the selection of "Save user name and password." If the authentication information is not stored in the key-ring, then the EGT uses session authentication, which means that the credentials supplied are used only for the lifetime of the Eclipse workbench instance.

If authentication information is not stored in the key-ring or the authentication information (key-ring or session) is not valid, the EGT will prompt for authentication information when it has to access the Guvnor repository:


If authentication fails, the EGT will retry once and then issue an authentication failure error. (If an authentication failure error occurs, you can retry the same operation and supply different authentication information.) Note that the EGT calls the Guvnor repository at various times, such as when determining if resource updates are available, so, if you use session authentication, the authentication dialog will appear at different times during the Eclipse workbench session, depending on what actions you take. For ease of use, we recommend saving the authentication information in the Eclipse key-ring. (The Eclipse key-ring file is distinct from key-ring files found in some platforms such as Mac OS X and many forms of Linux. Thus, sometimes if you access a Guvnor repository outside the EGT, the key-ring files might become unsynchronized and you will be unexpectedly prompted for authentication in Eclipse. This is nuisance, but your usual credentials should apply in this case.)

Once the Guvnor connection wizard is complete, the new Guvnor repository connection will appear in the Guvnor Repository Explorer. You can then expand the tree to view Guvnor repository contents.


The Guvnor Repository Explorer view contains tree structures for Guvnor repository contents. As described above, there are menu and tool-bar actions for creating Guvnor repository connections. The red “X” in the tool-bar and “Delete” in the menu removes a Guvnor repository connection, and the “Refresh” menu item reloads tree content for the selected node. Finally, there are a number of tool-bar/menu items in support of “drill-into” functionality: one the tool-bar these are represented by the house (“return to top level/home”) and the arrows (go into/back). Drill-down is useful when working with deeply nested tree structures and when you wish to concentrate on only branch of the tree. For example, drilling into the “defaultPackage” node shown above changes the tree view to:


That is, we see only the contents of “defaultPackage” in the tree. Clicking on the house button, or selecting “Go Home” returns the tree to the top-level structure shown in the previous picture above.

There are a number of operations that can be performed on Guvnor repository files. Selecting a file in the Guvnor repository causes the Eclipse Properties view to update with details about that file:


Double-clicking on a folder (directory) in the tree will cause that folder to expand if collapsed and collapse if expanded. Double-clicking on a file in the tree will cause a read-only editor in Eclipse to open, showing the contents of that file:


Dragging a file from the Guvnor repository tree to a folder in an Eclipse local project (for example in the Eclipse Resource Navigator view) will cause a copy of that file to be made in the local Eclipse workspace. (Note: You can also “Save As...” when a file is open in a read-only editor to save a local writable copy of the contents. Doing so, however, will not associate the file created with its Guvnor source.) Finally, you can view the revision history of a file selected in the tree using the “Show History” context menu item. (The details of resource history will be discussed below.)

As mentioned in the Introduction, the main purpose of the EGT is to allow development using resources held in a Guvnor repository. There are two method of getting local copies of Guvnor repository resources:

When local copies of Guvnor repository files are created, the EGT sets an association between the local copy and the master file in the repository. (This information is kept in the (normally) hidden .guvnorinfo folder in the local project and, like all metadata, should not be changed by end users.) This association allows for operations such as update and commit in synchronization with the master copy held in the Guvnor repository. The EGT decorates local resources associated with Guvnor repository master copies. This decoration appears in Eclipse views conforming to the Eclipse Common Navigator framework, such as the Eclipse Resource Navigator and the Java Package Explorer. The image below shows decoration in the Eclipse Resource Navigator:


Note the Guvnor icon decorator on the top right of the file images, and the Guvnor revision details appended to the file names. (The presence/location of these can be changed. See "Guvnor plugin Preferences" for details.) Here we see that, for example, simpleRule.drl is associated with a Guvnor repository resource and the local copy is based on revision 3, with a 7-15-2008, 15:37:34 date/time stamp. The file deleteTest.txt, however, is not associated with a Guvnor repository file. Further details about the association can be found in the standard Eclipse properties page, via the context menu “Properties” selection:


The EGT contributes a property page to the standard Eclipse properties dialog, the contents of which are shown above. The specific Guvnor repository, the location within the repository, the version (date/time stamp) and revision number are displayed.

The EGT provides a number of actions (available through the “Guvnor” context menu on files) for working with files, both those associated with Guvnor repository master copies and those not associated. The actions are: 1.Update 2.Add 3.Commit 4.Show History 5.Compare with Version 6.Switch to Version 7.Delete 8.Disconnect Each of these actions will be described below.

Update Action:

The Update action is available for one or more Guvnor resources that are not in synchronization with the Guvnor repository master copies. These resources would not be in synchronization because either/both (1) there are local changes to these resources or (2) the master copies have changed in the Guvnor repository. Performing the Update action replaces the local file contents with the current contents from the Guvnor repository master copies (equivalent to “Switch to version” for latest version).

Add Action

The Add action is available for one or more local files that are not associated with a Guvnor repository master copy. Choosing the Add action launches the “Add to Guvnor” wizard:


The first page of the wizard asks for the selection of the target Guvnor repository and gives the choice to create a new Guvnor repository connection (in which case the second page is the same as the Guvnor Connection wizard described above). Once the target Guvnor repository is chosen, the wizard then asks for the folder location to add the selection files:


Here I have selected the folder “anotherPackage” as the destination location1. Clicking on “Finish” adds the selected files to the Guvnor repository and creates an association between the local and Guvnor repository files. (Not that the wizard will not allow for overwrite of existing Guvnor repository files – another target location must be chosen.)

Compare with Version Action:

The Compare with Version action is enabled for one Guvnor repository associated file. This action first opens a wizard asking for the version for comparison (with the local file contents):


Once the revision is selected, the action opens the Eclipse compare editor (read-only):


This editor uses Eclipse-standard comparison techniques to show the differences in the two versions. In cases where there are no differences, the editor will not open: rather, a dialog saying that there are no differences will appear.

Switch to Version Action:

The Switch to Version action is enabled for one Guvnor repository associated file. First the Switch to Version action prompts for selection of version:


Once the version is selected, the Switch to Version action replaces the local file contents with those from the revision selected.

Delete Action:

The Delete action is enabled for one or more Guvnor repository associated files. After confirmation via a dialog, the Delete action removes the files in the Guvnor repository and deletes local metadata for the Guvnor repository association.

Disconnect Action:

The Disconnect action is enabled for one or more Guvnor repository associated files, and removes local metadata for the Guvnor repository association.

Guvnor Resource History View:

The Guvnor Resource History view should details about revision history for selected files, both local and those in Guvnor repositories. The initial state of this view is:


The Guvnor Resource History view is populated by “Show History” actions in either the local “Guvnor” context menu or in the context menu for a Guvnor repository file in the Guvnor Repository Explorer. Once this action is performed, the Guvnor Resource History view updates to show the revision history:


Here we see that the file “simpleRule.drl” has three revisions. Double clicking on a revision row (or context menu “Open (Read only)”) opens an Eclipse read-only editor with the revision contents. (Note: You can also “Save As...” when a file is open in a read-only editor to save a local writable copy of the contents. Doing so, however, will not associate the file created with its Guvnor source.)

The EGT provides a preference page in the “Guvnor” category:


The preferences cover two categories: Guvnor repository connections and local Guvnor repository resource decorations.

Guvnor Repository Connection Preferences

There are two preferences that can be set for Guvnor repository connections, and these are used when creating new connections. The first is a default Guvnor repository URL template, which can make it easier to create multiple similar connections by simply changing part of the field, such as the host name. The second is whether saving of authentication information in the Eclipse platform key-ring should be enabled by default. As with the Guvnor repository URL template, actually whether to save a specific instance of authentication information in the Eclipse platform key-ring can be determined when actually creating the connection. That is, both of these preferences are simply convenience values set to reasonable defaults.

Local Guvnor Repository Resource Decoration Preferences

The second category of preferences provided by the EGT deals with how decoration of local resources associated with Guvnor repository resources is presented. Since the Guvnor repository is not a substitute for a SCM, and since SCM tools in Eclipse tend to decorate local resources, it is useful to be able to control just how the EGT decorate its local resources to avoid messy conflicts with SCM packages. In the “File Decoration” section of the preference page, you can choose the location (top right, bottom right, top left, bottom left) of the decoration icon, or you can choose not to display it. In the “Text” section, you can format the Guvnor metadata that is appended to the file names: Whether to show an indicator (>) when the local file has changes not committed back to the Guvnor repository. Whether to show the revision number. Whether to show the date/time stamp. Any changes to these preferences take effect immediately upon clicking the “Apply” or “Ok” buttons.

As we already know, Guvnor provides a set of editors to author rules in different ways. According to rule’s format a specialized editor is used. Some of the supported formats are: brl (guided editor), drl (plain editor), dsl (dsl editor), template (guided editor) and decision table (decision table editor).

One of the features introduced in Guvnor 5.2 was the ability to embed Guvnor's editor in you own (Web) Applications. So, if you want to edit rules, processes, decision tables, etc. In you applications without switch to Guvnor, you can.

This section covers all the steps you need to follow to embed Guvnor's editors in your Web Application

Depending on the parameters used to invoke the Editor, you can use it in 3 different ways: BRL Edition Mode, Edition of Existing Assets Mode and Create New Asset Mode.

BRL Edition Mode is used if you want to use BRL code in your application. You can provide multiple BRL sources to the Editor, each of them will be converted to a temporal RuleAsset (a Guvnor’s internal representation) and displayed in a separate editor.

These are the parameters you must use in the invocation of StandaloneEditorServlet to open Guvnor's Editor in BRL Edition Mode:


All the assets created when using this mode are temporal. They are never going to be persisted in Guvnor. The purpose of this mode is to use just the Guided Editor and not Guvnor persistence layer. You can provide one or more initial brls, work on them using the Guided Editor and then retrieve the modified source from your application using javascript. Every time you want to edit a rule, you must provide its brl code.

Warning

BRL syntax is an internal format used by Guvnor. It is not supposed to be used in external applications, so drastic changes in its syntax can occur without any advise.


We already covered all the HTTP parameters that must be used for each Edition Mode. You can combine these parameters with some others to customize the appearance and behavior of the editor.

This part covers installation and administration issues of Drools Guvnor.

Drools Guvnor is a web application that can run in multiple environments, and be configured to suit most situations. There is also some initial setup of data, and export/import functions covered.

The Guvnor application is packaged as a .war file, which can be deployed to any application server (such as JBoss AS, ...) or servlet container (such as Tomcat, ...) out-of-the-box.

Installation is simple: download, deploy, start and surf.

  1. If you don't have an application server or servlet container, download and install one. For example, download JBoss AS.

  2. Download the Guvnor distribution from the download site. In the download zip, there's 1 war file per app server version, for example guvnor-5.2.0-jboss-eap-5.1.war for JBoss EAP 5.1. Use the war file best suited for your app server. Essentially there's little difference between those war files: mostly it's a matter of excluded jars which are already available on the app server.

    If no war specifically for your app server exists yet, take the latest Tomcat war. It might require minor configuration tweaks. Consult our wiki for specific tips. The community has been able to make it run on various platforms. Patches (pull requests) to expand our war assemblies for another app server or version are welcome.

  3. Optionally rename that war file to guvnor.war to have a nicer URL. For the rest of the manual we'll presume you've done this.

  4. Optionally customize the configuration. First explode (unzip) the war file, and change any configuration and then unexplode (zip) it again.

  5. Deploy the war file by copying it into the deployment directory of the app server. For JBoss AS 5 and 6, that directory is server/default/deploy. Alternatively you can first explode (unzip) the war file and copy that exploded directory. Note: in JBoss AS, the exploded directory name must end with the suffix .war.

  6. Start the app server. For JBoss AS 5 and 6, run $JBOSS_AS_HOME/bin/run.sh (or run.bat).

  7. Surf to the Guvnor webapp. This will probably be at localhost on port 8080, for example at http://localhost:8080/guvnor-5.5.0.Final (the url depends on the name of the war file you're using).

Guvnor uses the JCR standard for storing assets such as rules. The default implementation is Apache Jackrabbit. This includes an out of the box storage engine/database, which you can use as is, or configure to use an existing RDBMS if needed.

Assuming you are using on of the JBoss platforms, running Guvnor for the first time will create a database in the bin/ directory of the application server. There you will find the default Jackrabbit configuration file, namely repository.xml, and a repository directory which contains your repository data. Both of these are created automatically for you.

The location of the data store should be a secure location, that is backed up. The default location may not be suitable for this, so the easiest way is to set a more suitable location. If you want to change this, please make sure you have stopped Guvnor (i.e. stopped the app server or un-deployed the application).

To change the location, unzip the Guvnor WAR file, and locate the beans.xml file in the WEB-INF directory. This is a JBoss Seam configuration file (Seam 3 is the framework used) which allows various parts of the system to be customized. When you have located the beans.xml file, you should see something like the following:


  <guvnorRepository:GuvnorBootstrapConfiguration>
    <s:modifies/>

    <!-- JackRabbit  -->
    <guvnorRepository:properties>
      <s:entry><s:key>org.drools.repository.configurator</s:key><s:value>org.drools.repository.jackrabbit.JackrabbitRepositoryConfigurator</s:value></s:entry>
      <!--  the root directory for the repo storage the directory must exist. -->
      <!--<s:entry><s:key>repository.root.directory</s:key><s:value>/opt/yourpath</s:value></s:entry>-->
    </guvnorRepository:properties>

    ...
  </guvnorRepository:GuvnorBootstrapConfiguration>

Find the component with a name of GuvnorBootstrapConfiguration and its section for JackRabbit configuration, then the key property with the name of repository.root.directory.

If you un-comment this key element (as in the example above it is commented out), you can set whatever file-system path you need for the repository data to be stored in. You can also use this to move the repository around. In that case, when you have set the location in the beans.xml you can simply move the repository.xml AND the repository directory to the new location that you set in the beans.xml.

If there is no repository.xml configuration file, or the repository directory at the location specified (or in the default location) then Guvnor will create new empty ones.

There are many more options which can be configured in the repository.xml, but for the most part, it is not recommended to change the defaults.

In some cases it may be a requirement that you use an external RDBMS, such as Oracle, MySQL, or Microsoft SQL Server as the data store - this is permitted and recommended as storing your repository data in an external RDBMS is much more reliable than the default file-system storage option. The JackRabbit repository.xml file contains the information where your repository data is stored, so changes to this file are necessary for RDBMS setup. You have two options to make changes to repository.xml, namely make all changes manually, or use the Guvnor Repository Configuration Manager.

If you opt for the manual configuration, the easiest thing to do is to start up Guvnor with defaults (or with a suitable repository.root.directory directory as specified above) to let it generate the default repository.xml. Locate the repository.xml file that was generated, and open it - it will be annotated with comments describing many of the different options. From here on, you will need to know a little about Jackrabbit Persistence managers. There are a few persistence managers, some are database specific (eg Oracle). There is a SimpleDBPersistenceManager which works with any database that supports JDBC - you also specify the database type, so it uses the specific DDL to create the table structure (all major databases are supported).After you have added your configuration options, start the Guvnor application again. Guvnor will then create the database tables the first time it is started up if it is running against a fresh (empty) RDBMS - so its important to note that the user credentials supplied have permissions to create tables (at least initially, on first run, after that they could be locked down).

Using the Repository Configuration Manager in Guvnor is often a lot easier and a less error-prone options to make the necessary configuration changes in repository.xml. With Guvnor application running, select the Administration tab in the left-hand-side navigation bar, then select the Repository Configuration link.


Repository Configuration Manager includes template configuration files for many external RDBMS types. The first thing you have to do is the select the RDBMS type from the dropdown menu and select if you are using JNDI to look up your data source or not.


If you opt to use JNDI, you have to enter the JNDI name configured in your deployed data source. Otherwise you need to enter your RDBMS information.


At this point you are ready to generate your repository.xml give your RDBMS information. Click on the "Generate repository config" button.


You can download the generated repository.xml file by clicking the "Save Configuration" button, or copy/paste the generated text manually. Replace your existing repository.xml with the generated one and restart Guvnor for the changes to get picked up.

Guvnor supports running on either JackRabbit and ModeShape as the underlying JCR-2.0 implementation. By default Guvnor ships using JackRabbit. However if you want to switch to using ModeShape then you need to install ModeShape as a service in JBossAS-5.x. Check the ModeShape project and download and install ModeShape 'kit' version 2.5.0 or later. After installing the kit, you should have a modeshape-service.jar directory in your deploy directory. Since ModeShape 2.5.0 only support deployment to JBoss-5.x, make sure to also use the guvnor-5.2.0-jboss-eap-5.1.war. Now we can remove some jars from the guvnor WAR that are no longer needed, and in fact will cause classloading issues if you don't remove them:

[localhost]$ rm -f WEB-INF/lib/jackrabbit-*
[localhost]$ rm -f WEB-INF/lib/hibernate-* WEB-INF/persistence-api-1.0.jar WEB-INF/lucene-*.jar
[localhost]$ rm -f WEB-INF/lib/jcr-2.0.jar

Next you need to edit the WEB-INF/beans.xml file to switch over to ModeShape. Comment out the JackRabbit section and uncomment the ModeShape section:


  <guvnorRepository:GuvnorBootstrapConfiguration>
    <s:modifies/>

    <!-- JackRabbit  -->
    <guvnorRepository:properties>
      <s:entry><s:key>org.drools.repository.configurator</s:key><s:value>org.drools.repository.jackrabbit.JackrabbitRepositoryConfigurator</s:value></s:entry>
      <!--  the root directory for the repo storage the directory must exist. -->
      <!--<s:entry><s:key>repository.root.directory</s:key><s:value>/opt/yourpath</s:value></s:entry>-->
    </guvnorRepository:properties>

    <!-- ModeShape -->
    <!--
      passwords for the background users (logInAdmin and mailman), these need to match the setting
      you provided for JAAS (used by ModeShape only).
    -->
    <!--<guvnorRepository:properties>-->
      <!--<s:entry><s:key>org.drools.repository.configurator</s:key><s:value>org.drools.repository.modeshape.ModeShapeRepositoryConfigurator</s:value></s:entry>-->
      <!--<s:entry><s:key>org.modeshape.jcr.URL</s:key><s:value>jndi:jcr/local?repositoryName=brms</s:value></s:entry>-->
      <!--<s:entry><s:key>org.drools.repository.secure.passwords</s:key><s:value>false</s:value></s:entry>-->
      <!--<s:entry><s:key>org.drools.repository.logInAdmin.password</s:key><s:value>logInAdmin</s:value></s:entry>-->
      <!--<s:entry><s:key>org.drools.repository.mailman.password</s:key><s:value>mailman</s:value></s:entry>-->
    <!--</guvnorRepository:properties>-->

  </guvnorRepository:GuvnorBootstrapConfiguration>

Note that you can use encrypted passwords by setting the org.drools.repository.secure.passwords setting to true. To encrypt a password use:

[localhost]$ java -cp client/jboss-logging-spi.jar:common/lib/jbosssx.jar org.jboss.resource.security.SecureIdentityLoginModule <password>

ModeShape does not support 'trusted' access like JackRabbit does, and by default uses JAAS for authentication and authorization. For more detail on Guvnor and Security see the next section about Security. To use JAAS and the modeshape policy comment out the defaultAuthenticator section and uncomment the jaas-configuration section, and change the policy name from 'other' to 'modeshape':



  <security:IdentityImpl>
    <s:modifies/>

    <!-- No real authentication: demo authentication for demo purposes -->
    <security:authenticatorClass>org.drools.guvnor.server.security.DemoAuthenticator</security:authenticatorClass>

    <!-- JAAS based authentication -->
    <!--<security:authenticatorName>jaasAuthenticator</security:authenticatorName>-->

    <!-- IDM based authentication (supports LDAP, see Seam 3 and PicketLink IDM documentation) -->
    <!--<security:authenticatorClass>org.jboss.seam.security.management.IdmAuthenticator</security:authenticator>-->
  </security:IdentityImpl>

  <!--<security:jaas.JaasAuthenticator>-->
    <!--<s:modifies/>-->
    <!--
      The following one will use the jaas configuration called "other",
      which in jboss AS means you can use properties files for users.
    -->
    <!--<jaasConfigName>other</jaasConfigName>-->
  <!--</security:jaas.JaasAuthenticator>-->

You may have noticed the settings of two passwords in the modeshape property settings for the 'admin' and 'mailman' users. These users are used by guvnor to perform background tasks. Now that we are no longer allowing for anyone to run as 'guest', we need to ass these two users to the modeshape users and roles files. Open the conf/props/modeshape-users.properties file and add the mailman and admin users,

admin=admin
mailman=mailman

Finally open the conf/props/modeshape-roles.properties file and add the admin and mailman roles,

admin=connect,admin
mailman=connect,readonly,readwrite

By default JackRabbit uses InMemory storage, which is configured in the modeshape-service.jar/modeshape-config.xml. To change this we recommend reading the modeshape documentation. To use a referenced JNDI data source, replace the <mode:source></mode:source> segment with the following:


<mode:source jcr:name="store" mode:classname="org.modeshape.connector.store.jpa.JpaSource"
mode:dataSourceJndiName="your JNDI name"
mode:model="Simple"
mode:dialect="org.hibernate.dialect.HSQLDialect"
mode:referentialIntegrityEnforced="true"
mode:largeValueSizeInBytes="10000"
mode:retryLimit="3"
mode:compressData="false"
mode:predefinedWorkspaceNames="default,system"
mode:showSql="false"
mode:autoGenerateSchema="update"
mode:creatingWorkspacesAllowed="true"
mode:defaultWorkspaceName="default" />

Alternatively you can connect directly to a JDBC data source, use the same <mode:source> fragment as for JNDI except replace the mode:dataSourceJndiName attribute with these attributes:


mode:driverClassName=org.hsqldb.jdbcDriver
mode:username=sa
mode:password=
mode:url=jdbc:hsqldb:mem:target
mode:maximumConnectionsInPool=5

For purposes of illustration, the HSQL DB is being used, but simply replace the attribute values with the appropriate driver class name, username, password, and database URL. Don't forget to add a dependency to your JDBC jar, so the JDBC driver available in the classpath.

Please note that giving someone access to Guvnor indicates a level of trust. Being able to editing and build rules is providing a great deal of power to a user. Thus you should not open up Guvnor to your entire organization - but instead to a select few. Use https (http with TLS/SSL) where ever possible, even internally in a company network this is a good idea. Use this power wisely - this not a "run of the mill" application that provides read/write access to a database, but something much more power. Just imagine you are spider man - with great power comes great responsibility (of course even more so for super man).

Security is configured by using the beans.xml file in the war file. To customize this, you will need to unzip the WAR file, and locate the beans.xml file which is in the WEB-INF directory.

The JAAS standard is used as the underlying authentication and authorization mechanism, the upshot of which means its very flexible and able to integrate into most existing environments.

Out of the box, Guvnor shows a login screen, but no security credentials are enforced - the user name is used, but no password check is performed. To enforce authentication, you need to configure it to use an appropriate user directory, you may have Active Directory or similar already.

In the beans.xml file, you should located a security configuration section like the following:



  <security:IdentityImpl>
    <s:modifies/>

    <!-- No real authentication: demo authentication for demo purposes -->
    <security:authenticatorClass>org.drools.guvnor.server.security.DemoAuthenticator</security:authenticatorClass>

    <!-- JAAS based authentication -->
    <!--<security:authenticatorName>jaasAuthenticator</security:authenticatorName>-->

    <!-- IDM based authentication (supports LDAP, see Seam 3 and PicketLink IDM documentation) -->
    <!--<security:authenticatorClass>org.jboss.seam.security.management.IdmAuthenticator</security:authenticator>-->
  </security:IdentityImpl>

As you can see from above, the 2 "out of the box" options are pass through - which means any user is allowed in, or bypassed, in which case there is no login screen (e.g. you may be securing access to the app via a web server anyway).

Every application server supports advanced configurations which can work with your existing security infrastructure. The case of JBoss AS will be shown here as an example.


<security:identity authenticate-method="#{authenticator.authenticate}"
   jaas-config-name="other"/>

This will use the other JAAS config in JBoss AS. If you look in jboss-as/server/default/conf you will see a login-config.xml file. This file contains various configurations. If you use other like the one above, then it will look for users.properties and roles.properties in the conf/ directory for usernames and passwords to authenticate against. This is maintainable only for a fixed small number of users.

LDAP is perhaps the most popular choice for larger enterprises. Here is an example that works with Active Directory. You can get much more information on how to configure JBoss AS for all scenarios with LDAP from this wiki page and this wiki page.


<application-policy name="brms">
   <authentication>
      <login-module code="org.jboss.security.auth.spi.LdapExtLoginModule" flag="required" >
         <!--
            Some AD configurations may require searching against
            the Global Catalog on port 3268 instead of the usual
            port 389.  This is most likely when the AD forest
            includes multiple domains.
         -->
         <module-option name="java.naming.provider.url">ldap://ldap.jboss.org:389</module-option>
         <module-option name="bindDN">JBOSS\someadmin</module-option>
         <module-option name="bindCredential">password</module-option>
         <module-option name="baseCtxDN">cn=Users,dc=jboss,dc=org</module-option>
         <module-option name="baseFilter">(sAMAccountName={0})</module-option>

         <module-option name="rolesCtxDN">cn=Users,dc=jboss,dc=org</module-option>
         <module-option name="roleFilter">(sAMAccountName={0})</module-option>
         <module-option name="roleAttributeID">memberOf</module-option>
         <module-option name="roleAttributeIsDN">true</module-option>
         <module-option name="roleNameAttributeID">cn</module-option>

         <module-option name="roleRecursion">-1</module-option>
         <module-option name="searchScope">ONELEVEL_SCOPE</module-option>
      </login-module>
   </authentication>
</application-policy>

To use the above, you would put jaas-config-name="brms" in the security:identity tag in the beans.xml for Guvnor.

Similar configuration examples can be found for other directory services.

LDAP isn't the final word, you can use JDBC against a database of user name, or you can write your own login module to use any sort of weird and wonderful authentication and authorization systems that you may have to deal with (that would be an extreme case, but its possible). Refer to JBoss AS documentation (or documentation for your existing application server).

The above section talks about establishing identity and access for users. This section talks about granting specific permissions to these users (to control data visibility and access). This can be used to partition data, or to control access for "non power users" which can limit the damage they can do.


A common need and desire of the web interface of Guvnor is to be able to have users of different technical abilities interact with it. Another need is to be able to allocate people different sets of data to "own".

Typically users identities are managed in a centralized directory - application servers can integrate with these directories (e.g. active directory, LDAP) so users to Guvnor can be authenticated without having to create another duplicate identity. It is also possible (thanks to JAAS) to define what users have the "admin" role for Guvnor (note that an Admin user of Guvnor doesn't have to really be a system administrator). Further to this, Guvnor augments this identity with data specific permissions, which are managed in Guvnor itself.


Note that the above users identities are not stored in Guvnor, only their permission mappings are which are specific to Guvnor.

There are really two system wide roles: Users who are Administrators and users who are not. Administrators can see and do anything. Out of the box, the permission system is turned off, and every user is an administrator (this is pretty much how things used to work). There is also a system setting in beans.xml that can turn the permissions system on and off (so people can manually override if needs be). A administrator can also give other users admin rights, regardless of their roles in the external directory service.


There are several types of permissions: Per package: Package Administrator ("owns" a package - can deploy etc, but has no administrative rights to the system). Package developer - this permissions allows users to create new items, edit etc - but only at the package level (not deploy). They can also run and create tests. Package readonly - well this one is pretty obvious. Per Category: This is the "interesting" one - as assets (rules) can be tagged with multiple categories, you can use these to assign permissions to an "analyst" type of user. A user can be assigned multiple categories. A user can then edit and view any asset that is tagged in that category (regardless of package). A user that only has category permissions will not be shown any package views or details, and will only see the simple categories view. This allows administrators and managers to control exactly what these users can and can't see. Note that per category permissions can also be set as "read only" so a user can view all the assets in a category, but not make changes to them.


The per category "analyst" permissions are quite useful - you can also augment their permissions with a specific package (so on top of their category rights, they can see and play with a particular package - which may be used as a "practice" area, or test area for instance). This provides a few ways to manage permissions in a coarse or fine grained way, as suits the different types of users.

It is often needed to migrate your existing repository from one persistence manager schema to another. A typical scenario for this case is if you have existing rule assets in a repository using the default file-system configuration and would like to move to storing your existing data to a RDBMS. In these cases you can use the drools-ant JackrabbitMigrationAntTask which can easily convert all your repository data from one repository configuration to another repository configuration. Example configuration for this ant task can be:


<project default="migraterepo">
  <path id="migration.classpath">
    <pathelement path="${classpath}" />
    <fileset dir="/Users/tihomir/development/droolsjbpm/jboss-4.2.3.GA/server/default/deploy/drools-guvnor.war/WEB-INF/lib">
        <include name="**/*.jar"/>
     </fileset>
    <filelist refid="drools-ant" />
    <filelist refid="db-driver-jars" />
  </path>

  <filelist id="db-driver-jars" dir="/Users/tihomir/development/droolsjbpm/jboss-4.2.3.GA/server/default/lib">
    <file name="mysql-connector-java-5.1.11-bin.jar" />
  </filelist>

  <filelist id="drools-ant" dir="lib">
    <file name="drools-ant-${project.version}.jar" />
  </filelist>

  <taskdef name="migrate" classname="org.drools.contrib.JackrabbitMigrationAntTask"
    classpathref="migration.classpath" />

  <target name="migraterepo">
    <record name="migration-log.txt"/>
    <migrate verbose="true"
        sourcedir="/Users/tihomir/development/droolsjbpm/jboss-4.2.3.GA/bin/repository/"
        sourceconfig="/Users/tihomir/development/droolsjbpm/jboss-4.2.3.GA/bin/repository.xml"
        targetdir="/Users/tihomir/demo-jrmigration/targetrepo/"
        targetconfig="/Users/tihomir/demo-jrmigration/targetrepo/repository.xml" />
  </target>
</project>

In the above scenario JackrabbitMigrationAntTask is going to migrate all repository data configured in repository.xml defined in the sourcedir attribute, to the repository configured in repository.xml defined in the targetconfig attribute. Note that this data migration is a full migration, which means it migrates the entire repository which also makes it a good tool to use for backups as well. This blog post contains a video showing a full example on how to use the JackrabbitMigrationAntTask for repository migration.

To achieve, this, you can "explode" the deployment WAR file, and locate the Guvnor.html file, which will look something like the following:


<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
   <!-- Note you can append #asset=UUID to the end of the URL to preload a given asset.
      Also, if you appent #asset=UUID&amp;nochrome it will only show the asset without all the GUI "chrome"

      To select a locale, specify &amp;locale=en_US at the end of the URL to pick the appropriate bundle.
      -->
   <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
   <meta http-equiv="X-UA-Compatible" content="IE=EmulateIE7" />
   <title>JBoss Guvnor</title>

   ..........

</body>
</html>

Note that the above Guvnor.html file is fairly small (as most of the work is done by the GWT - the GUI is built dynamically in the browser). The parts you can customize are the style sheet - you can either edit the Guvnor.css (or better yet, take a copy, and change the style to be what you need), the "shortcut icon" (its what shows in the address bar in the browser etc - also change the "icon" link to be the same so it works in IE), and the header logo. The rest should be left as is, to allow the GWT components to be loaded and attached to the page. This html page is loaded only once by the browser when the user accesses Guvnor web GUI.

The best way to customize is to take a copy of the Guvnor.html file and then edit. You can also change the URL by editing the web.xml via the normal means.

This section covers the technical aspects of Guvnor, it is not necessary to use this if you are integrating or an end user of the application. However, Drools is open source, so build instructions form part of the manual.

You may want to build from source if you want to re-use components, or embed the application within another.


The above diagram shows the major components of the system and how they integrate and are deployed. The User Guide has more details on the parts that are highly configurable (e.g. database).

Guvnor is deployed as a WAR, which provides user interfaces over the web, and provides binary packages using URLs (or files). It uses the JSR-170 standard for data storage (JCR). JBoss Seam is used as the component framework, and GWT is used as the widget toolkit for constructing the AJAX-based web user interface.

This section will go over the steps necessary to build various components. Mostly this is automated, but the manual process is described for thoroughness.

Each module has a ready to go and up to date eclipse project configuration, so they can merely be imported into the eclipse workspace. These projects are generated by Maven. Use the mvn eclipse:eclipse command to refresh them in case they are wrong or outdated. They have been manually modified to have project dependencies which means that the code can be stepped through when debugging.

Some environment variables are required in eclipse (for Window: >Preferences->Java->Build path-> Classpath variables): the M2_REPO, as normal, to point to where Maven downloads shared dependencies. GWT_HOME should point to where you installed GWT. GWT_DEV must point to the platform specific "dev" JAR that ships with the version of GWT you have.

How to launch from Eclipse: unit tests can be launched, as normal (in which case only M2_REPO setup is needed, GWT does not need to be downloaded separately), or it can be launched it in hosted mode using the GWT browser, which is great for debugging (from GUI to back end, the code can be stepped through, and changes made on the fly and simply hit refresh). There is a Guvnor.launch file in in the guvnor-webapp directory. To launch Guvnor in debug mode, open the Run dialog (Run->Run), and then choose Guvnor from the list. Launching this will open a new window, with Guvnor in debug mode, ready to go.

Downloading and debugging Guvnor with GWT is optional, so if there are no GUI issues being worked on then this step can be safely skipped.

Refer to Chapter 12, Database configuration for for configuration options for database and filesystems.

Versions of assets are stored in the database along with the data.

When snapshots are created, copies are made of the entire package into a separate location in the JCR database.

For those familiar with JCR and Apache Jackrabbit, the *.cnd files are in the source for the node type definitions as some wish to view these. In a nutshell, a package is a folder and each asset is a file: an asset can either be textual or have a binary attachment.