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.
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.
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.
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
So let’s go now to see how Custom Forms are created and how are they configured inside Guvnor.
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.
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:
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.
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.
As you can see in the screenshot above, Custom Forms configuration consists of 5 elements:
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.
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
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.