Guvnor: Embed Asset’s Editor in your application.

Until now, if you wanted to create or edit rule assets in Drools you needed to enter Guvnor and work inside it. When Drools 5.2 sees the light of the day, there will be a new way: to embed Guvnor’s editors in your applications.

Guvnor’s Editors

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).

Guided Editor

DRL Editor

DSL Editor

Decision Table Editor

Since now, the only way to use these editor was using guvnor. But with Drools 5.2 you could embed any of these editors in your own application just like if they were standalone applications.

Standalone Editors and Guvnor

The standalone version of Guvnor’s Editors lets you to use just the editor window inside your applications. In order to be able to invoke a Editor instance from an external application, Guvnor must be running: Standalone Editor is just a part of Guvnor and not a different application.
So the first step is to have Guvnor deployed and running in a web/application server.

Using the standalone version of Guvnor’s Editor you can create or edit assets only inside existing categories and packages. You must configure at least one category and package with a valid model inside Guvnor to start working with this feature.

So, How do I embed these editors in my Application?

Guvnor defines a single entry-point to embed any of its editors in a web application: StandaloneEditorServlet. This servlet is found in /standaloneEditorServlet URL, and according t to the parameters you pass to it (parameters names and posible values are going to be explained later), you can open the editor in 3 different modes: BRL Edition Mode, Edition of Existing Assets Mode and Create New Asset Mode.
So, if you want to embed a Guvnor Editor in your application you will need to perform a request to /standaloneEditorServlet URL. Once open, you can interact with the editor using JavaScript.

Because you need to invoke JavaScript in order to interact with the editor, Guvnor and your application must be running in the same server. Otherwise you will find cross-domain JavaScript invocation problems.

Standalone Editor Modes

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.

1. BRL Edition 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.

The parameters involved in this mode are:

Parameter Name	Explanation	Allow multiple values	Example
packageName	The name of the package used to hold the created assets. The package must exist in Guvnor.	false	mortgages
categoryName	Each rule must have at least one category. The created rules will belong to this category. The category must exist in Guvnor	false	Home Mortgage
brlSource	The BRL source used by the editor. You can pass multiple brlSource parameters for multiple rules.	true	<rule> <name> Bankruptcy history </name> <modelVersion> 1.0 </modelVersion> <attributes> … </attributes> <lhs> … </lhs> <rhs> … </rhs> </rule>

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. You can provide one or more initial brls, work on them using the Guided Editor and then retrieve the modified source. Every time you want to edit a rule, you must provide its brl code.

Standalone Editor with 2 BRL Rules

2. Edition of Existing Assets Mode

You can use this mode if you want to use the Standalone Editor for edit assets that already exist inside Guvnor.
When editing existing assets, you will be able to save the changes in Guvnor as well as get the DRL and BRL code of them.

The parameters involved in this mode are:

Parameter Name	Explanation	Allow multiple values	Example
assetsUUIDs	The asset’s UUID. Use multiple parameters for specify multiple assets.	true	968c9b3c-bc19-40ba-bb38-44435956ccee

The asset’s UUID could be found using Guvnor (we are working on a way to get this information using Guvnor’s REST API).
When using this mode, you can edit assets from different types: like rules and decision tables.

Standalone Editor with Multiple Assets

3. New Asset Mode

You can use this mode if you want to start a new asset from scratch. Assets created using this mode could be persisted inside Guvnor using the “Save all Changes” button. At this moment, you can only create one asset at a time using this mode.

The parameters involved in this mode are:

Parameter Name	Explanation	Allow multiple values	Example
packageName	The name of the package used to hold the created asset. The package must exist in Guvnor.	false	mortgages
categoryName	The created rule will belong to this category. The category must exist in Guvnor	false	Home Mortgage
createNewAsset	Flag indicating that we want to start a new rule from the scratch	false	true false
assetName	The name for the asset to be created	false	New Rule
assetFormat	The format of the asset to be created. The format identifies the editor to be used.	false	brl (default) drl dsl gdst template And possibly any value defined in org.drools.guvnor.client.common.AssetFormats

Rule’s Sections Visibility Parameters

When you edit or create rules in BRL format (using the Guided Editor), you can choose which part of the rules would be visible (LHS, RHS and Attributes). You can specify this using 3 different HTTP parameters:

Parameter Name	Explanation	Allow multiple values	Example
hideRuleLHS	Should the LHS of the rules be hidden?	false	true false
hideRuleRHS	Should the RHS of the rules be hidden?	false	true false
hideRuleAttributes	Should the Attributes of the rules be hidden?	false	true false

Contraint Fact Types

When you edit or create rules in BRL format (using the Guided Editor), you can define a subset of the Fact Types defined in the rule’s package. When authoring the rule, you will only see the Fact Types defined in that subset. This is the same concept as Working-Sets. In fact, a Working-Set will be created and applied on-the-fly using the provided subset.

If you want to define this set of Fact Types you could use this parameter:

Parameter Name	Explanation	Allow multiple values	Example
validFactType	The name of a valid Fact Type. This is just the class name and not the fqn.	true	Bankruptcy ApplicationLoan

Interacting with the Editor

After the Editor is open, you can interact with it using JavaScript.
The Editor defines a JavaScript object in the Window where it is rendered. This object looks like this:

var guvnorEditorObject = {
    getDRL: function (callbackFunction),
    getBRL: function (callbackFunction),
    registerAfterSaveAndCloseButtonCallbackFunction: function (callbackFunction),
    registerAfterCancelButtonCallbackFunction: function (callbackFunction),
    getAssetsUUIDs: function()
}

The window.guvnorEditorObject defines 5 functions that you can use to interact with it. getDRL() and getBRL() receive a callback function as parameter. This function will receive a String containing the DRL or BRL of the rules you are editing.

The next 2 functions are for register callbacks for “Save”, “Done” and “Cancel” buttons. These callback functions don’t accept any parameter.
The last function is ised to retrieve the UUIDs of the assets you are editing. This is very useful when you are creating a new rule asset and you don’t know the UUID of it.

Conclusion

If you want to create rules in your applications using Guvnor’s Editors you can embed them in your applications now.

To invoke an Editor instance you need to perform a HTTP Request to /standaloneEditorServlet URL. According to the parameters passed, you could use Guvnor’s Editors in 3 different ways.When you need to interact with Guvnor’s Editor, you can use a JavaScript object defined in the window/frame where it is open.

Handy Resources

If you want to try this feature, you need to get the latest snapshot of Guvnor 5.2 version.

I also have created the following files to test all the functionalities while I was developing them. You can use them if you want to make a quick test, or to see how your applications should interact with Guvnor’s Editors.
You could download them and change the ACTION attribute of the form they have.

• brlEditor.html: Shows how to open an Editor for 2 BRL sources.
• newAssetEditor.html: Shows how to create a new Asset from the scratch. You can select from different Asset Formats.
• assetEditor.html: Shows how to edit existing assets. You will need to change the harcoded Asset’s UUIDs.
• GECallbackFunctions.txt: Shows the different function you can invoke on guvnorEditorObject. You can use frebug to execute these functions.