JBoss.orgCommunity Documentation

Chapter 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

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

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

Using the Embedded 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.

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 to the parameters you pass to it (parameters names and possible 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 opened, you can interact with the editor using JavaScript.

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.

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

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.

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

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