Guvnor Guided Editor: Custom Forms

These past days I was busy trying to implement the first version of Custom Forms for Guvnor’s Guided Editor. The idea is to enhance the way users author their rules, and in particular the restriction values they use in those rules.

Authoring rules without Custom Forms

Previous to this feature, when users want to add a restriction on a Fact field they must choose one of the three available options: Literal Value, Formula or Expression Editor.

Constraints Values Popup

These options are enough for create basic rules. But if you want to have more control over the possible values a field could have while authoring a rule you, then these three options are not enough.

One way to get more control on what users write is using Fields Constraints. But right now, they only work for post-authoring validation.

What is a Custom Form?

Custom Forms are for situations where selecting a value for a restriction involves some business logic. Suppose you have Address class with a country attribute. You might want to limit rules’ authors to enter valid names, and not just a plain string. Another case could be he use of internal codes for some other attribute that need to be retrieved from external systems.

For situation like those described above, Guvnor needs a way to communicate with external systems to get business validated values.

So, for the first example it would be nice to open a popup containing a Google Map where users could select a country name by clicking on it. This is one of the main purposes of Custom Forms. The following screenshot shows how this should look like

Custom Form Popup

So let’s go now to see how Custom Forms are created and how are they configured inside Guvnor.

Custom Form creation

Custom Forms are external web applications deployed in the same server Guvnor is. The Custom form must be accessible through an URL via HTTP GET method. You can use whatever technology you want for creating this form. Guvnor will open a popup containing an iframe and will load the form using its URL.

Guvnor / Custom Form Communication

The communication between Guvnor and the external application is performed using HTTP parameters (for Guvnor -> Custom Form communication) and DOM inspection (for Custom Form -> Guvnor communication).

Every time Guvnor invokes the Custom Form’s URL it will pass 4 GET parameters:

  1. factType: the short class name of the Fact that is being edited.
  2. fieldName: the name of the Fact’s field that is being edited.
  3. cf_id: the id of any previously selected value. Guvnor doesn’t use this value at all. It is only used by the external application to restore any previous state when editing a value. This value is empty the first time a Custom Form is opened.
  4. cf_value: The previously selected value. This value is empty the first time a Custom Form is opened.

The Custom Form could use this values to configure itself and must let users to select a new value for the field of the constraint that is being edited. Most of the times, the value itself is not meaningful for the external application. For example, if the external form let us choose a User name from a list, the external system might only cares about its ids. Guvnor in the other hand is only interested in the value of the name itself, because it is that value the one that will be used for the rule. But the next time a user edits the rule and wants to modify the User name of the constraint, the id of the User could be very useful for the External Form in order to restore any state. That is why Guvnor keeps 2 pieces of information for Custom Forms values: an internal id, and the value itself.

In order to get the selected value from the Custom Form, Guvnor uses javascript to introspect the external iframe DOM and retrieve the values. The external application must contain 2 <input> elements in the root container with ids: “cf_id” and “cf_value”. Guvnor will read the values of these input elements and store them. The value will be used in the rule (just like a literal value) and the id will be used in all the consequent invocations of the Custom Form.

Custom Form Configuration Inside Guvnor

Custom Forms are meta-data associated to a Fact’s field. So the better place to configure them are Working Sets.

The Working Set Management window now have an extra tab called “WS Custom Forms”. There you can configure different Custom Forms for different fields. A field can only have one Custom Form configuration in a Working Set.

Custom Form Configuration Panel

As you can see in the screenshot above, Custom Forms configuration consists of 5 elements:

  1. Fact Type: You must choose from one of the working set’s fact types.
  2. Field: This combobox is is filled in with the fields names of the Fact Type selected before.
  3. UR: The URL of the custom form application that will be used for setting the field value in a restriction.
  4. Width: The width of the opening popup.
  5. Height: The height of the opening popup.

Using Custom Forms in Guided Editor

Once you have configured the Custom Forms inside a Working Set, you can start using them in your guided editor. To do this you must enable the Working Set first, and then start creating restrictions as you always did.

When you add a restriction to a field that has a Custom Forms configuration associated, the configured URL will be opened instead of the regular popup (shown in figure 1). The selected value will be added to the guided editor in a button widget. When the user clicks this button, the popup will be shown again.

Custom Form Popup

An example

A screencast is worths 1000 screenshots, that is why I have created this little demo: http://plugtree.com/downloads/screencasts/CustomForms_demo.htm

There you can see how Custom Form are configured and used.

The External Application code could be found here: http://plugtree.com/downloads/screencasts/index.jsp.txt

Conclusion

Guvnor now support custom business logic to fill constraints values while authoring rules using Guided Editor. You can assign URLs to Fact fields using Working Sets; this URLs will be shown in Guided Editor when creating rules.

Custom Forms are external web applications deployed in the same server where Guvnor is. You can use any web technology you want to create this forms.

And, as I always say, this is an experimental feature. Feel free to use it and test it. Comments and constructive criticisms are always welcome.


Comments are closed.