...

Table of Contents
maxLevel 8 minLevel 2

OpenCDS Guvnor 5.4 and DSL Best Practices

...

V.     Common Patterns for Creating Responses. 30

A.      Write me….. 30

 Change Log

Introduction

The objective of this document is threefold:

• to list “pot-holes” (aka      “bugs”, “flaws”, or “annoyances”)       in Drools Guvnor 5.4,
• to furnish techniques to      avoid these “pot-holes,” and
• to provide patterns and      best practices for creating re-useable DSLs in Guvnor for use in writing      clear and reviewable rules for OpenCDS.      

Many of the “pot-holes” that were present in Drools Guvnor v5.3 have been fixed in this version, but some of the fixes have introduced a new “gotcha.”  It is our hope that the pot-holes will eventually all be fixed in future versions of Guvnor, and that the “pot-hole” portion of this document will no longer be needed.

This document will also furnish some common patterns to accomplish certain tasks in building rules for OpenCDS in Guvnor.

I.                   Pot-Holes

A.     Known “pot-holes” in Guvnor 5.4

This list may not be comprehensive, but it represents the things that we bumped into repeatedly.  If you have found other “pot-holes”, or have developed work-arounds, please either update this document with what you have learned, or let us know so that we can update this document.

1.     No Warning on Close without Save

still an issue in 5.4

...

Introduction

The objective of this document is threefold:

• to list “pot-holes” (aka      “bugs”, “flaws”, or “annoyances”)       in Drools Guvnor 5.4,
• to furnish techniques to      avoid these “pot-holes,” and
• to provide patterns and      best practices for creating re-useable DSLs in Guvnor for use in writing      clear and reviewable rules for OpenCDS.      

Many of the “pot-holes” that were present in Drools Guvnor v5.3 have been fixed in this version, but some of the fixes have introduced a new “gotcha.”  It is our hope that the pot-holes will eventually all be fixed in future versions of Guvnor, and that the “pot-hole” portion of this document will no longer be needed.

This document will also furnish some common patterns to accomplish certain tasks in building rules for OpenCDS in Guvnor.
 

Pot-Holes

Known “pot-holes” in Guvnor 5.4

This list may not be comprehensive, but it represents the things that we bumped into repeatedly.  If you have found other “pot-holes”, or have developed work-arounds, please either update this document with what you have learned, or let us know so that we can update this document.

1.     No Warning on Close without Save

still an issue in 5.4

All of the “Assets” that are part of a package can be opened for editing.  They will all show a gray “X” on the right-hand side of the tab at the top of the screen when you hover your mouse over the tab.  You need to think of this “X” as meaning “revert” or “abort,” because it will happily throw away all the work you have just done on the asset, with no warning.

2.     Inconsistent Refresh of Elements on Screen

still an issue in 5.4, but improved

There are not as many cases where the screen does not match what has been saved, but there is still at least one case where this happens.  If you rename an asset such as a rule, it will remain on the screen with the former name, even though the new name has actually been saved.

3.     Possible to Add Invalid DSL to a Guided Rule

no longer an issue in 5.4

4.     Possible to Permanently Damage a Guided Rule

no longer an issue in 5.4

5.     Possible to put a Package into Inconsistent State

no longer an issue in 5.4

6.     Possible to Archive Global Area

no longer an issue in 5.4

It is possible to archive the Global Area.  If you did this in 5.3, it destroyed the Global Area, permanently.  In 5.4, it merely archives the contents of the Global Area, and the contents can be retrieved using the Administration tools, if necessary.

7.     Possible to Add an Asset to Multiple Packages

still an issue in 5.4

It is possible to create a new DSL or Enumeration (and possibly other types of assets) and have them become an unintended asset of more packages than the single package you specified when you created it.  This sometimes happens when you have more than one package open as you create the element, and other times it happens for no apparent reason.  For example, if you create a new Enumeration that you intend to be a part of a specific package, but you have the Global Area (and possibly other packages) open when you create the Enumeration, it will be added to all the other packages that are currently open.

8.     Saving the Package and Signing Out

still an issue in 5.4 (was present in 5.3, but not documented)

When you save a package and “Sign Out”, Guvnor will happily throw away all of any unsaved work you have done on any open assets within that package, with no warning. 

9.     Some Assets from Global Area Randomly Appear or Disappear from Active Package

still an issue in 5.4 (was present in 5.3, but not documented)

This may be just a different view on Problem # 7.  Although any DSL you have specifically copied from the Global Area to your current working package will remain an asset in that package, other DSLs from Global will randomly appear or disappear from the working package.  While they are present, they can be used.  If they don’t show at a particular point, they also cannot be added to a rule, and a build of the package will generate errors.

10.

...

    Using Techniques to “refresh” Lists or Views may Refresh Modified Assets Elsewhere

new issue in 5.4

They resolved most of the issues around disparities between what is “saved” and what shows in a list of assets, or even the contents of an asset.  However, this has introduced a new problem that is apparently a side-effect of the “refresh” fixes.  A modified asset that has not been saved may get “refreshed” from disk if you do anything that causes a package list of assets to be refreshed (such as clicking on a button named “refresh list”).

11.

...

     Enumerations Do Not Allow Comments

new issue in 5.4

In Guvnor 5.3 it was possible to imbed comments in Enumeration assets.  In Guvnor 5.4, this will cause the enumerations to fail, except in one specific structure:  You can add a block comment to the last line of the enumeration (e.g., /* comment… */ ).  A comment in any other location will cause the enumeration to fail to be processed at all by Guvnor.  Since OpenCDS has a tool to export enumerations which placed a comment at the beginning of the enumeration list, this will have to be removed, or your enumerations will not show up in DSLs.
 

...

Work-Arounds for the Pot-Holes

The following approaches can help you avoid the pot-holes, or recover from falling into them.  Of course, it is always better to avoid them in the first place…  J

1.     Develop Habit of Save before Changing to a Different Tab EVERY TIME

Before you click on another tab, use the File menu, and select “Save changes.”  Some things you do in another tab can cause the screen to be refreshed from the last saved value, thereby losing all your updates in any open tabs.

2.     Develop Habit of Save before Close EVERY TIME

Instead of using that “X” to close the asset, use the File menu, and select “Save and Close.”  Developing that habit will avoid a lot of lost work. 

...

NOTE:  We maintain a text copy of all the import statements for vMR version 1.0 in the OpenCDS Maven project, as a text resource in the vMR internal module.  In most cases, you can probably use that list without changes.

3.     Develop Habit of Exporting the Guvnor Repository FREQUENTLY

Because it is possible to get Guvnor packages and rules into inconsistent or “locked” and unopenable states, it is critical to export the package to create backups.  You will avoid a lot of grief if you make it a habit to always do an export frequently and especially before you do any of the following:

• Rename anything

• Remove a DSL or an Enumeration (no longer      as big an issue as it was in 5.3, but still a good idea)

• Import an updated Model

4.     Techniques to Refresh Screen

There are three common techniques to refresh the screen.  These were more useful in 5.3 than they are in 5.4, which is a lot better about refreshing the screen.  Note that all of these techniques may refresh assets that have been changed, thereby losing any changes you have not saved.  Save First!

• Click the “Refresh List”      button in the Assets view of the package.       This will often make an asset that you just created appear in the      list, or an asset that you just deleted/archived disappear from the list.

• Click the icons which      change the view of Knowledge Base Packages from nested to listed.  This will close the group of package      listings and reopen them, and tends to refresh all the lists in all      packages.

• When all else fails, and      you know that you have something saved in the package, but it doesn’t      appear appropriately (or the contents seem to be from the previous      version), you can refresh everything, including the element lists that      show when you are adding things to a Guided Rule, by logging out and      logging back in. 

• NOTE:  All of the above methods may refresh      assets that are currently open (and possibly have changes!).  Save all your changes first!

5.     Avoid Damaging a Guided Rule

Guvnor 5.4 no longer appears to have a problem with “damaged rules,” but the following suggestions are still probably good ones…

...

You can avoid ever having damaged rules by following this advice:

• Never rename a DSL.  If you want it renamed, create a new DSL      with the new name, and copy and paste the content of the original rule      into the new rule.  Once you have      tested that new DSL, you can then go through all of the rules that used the old DSL, and delete the      references to the old DSL, and add in the new DSL.  Once you have completed the changes,      then you can delete the old DSL.

• Never rename an      Enumeration.  If you want it      renamed, create a new one with the new name.  Go through all the DSLs that reference that Enumeration, and correct them      to the new name.  Once you have      completed the changes, then you can delete the old Enumeration.

• Always create your      rules in a package.  This allows      you to use recovery techniques if you damage the rule or package.  In fact, I have personally decided that      it is safer never to have a Guided Rule in the Global Area, although I use      the Global Area for all DSLs, and for common enumerations.

• Always test your DSL      files in throw-away rules before you start using the DSL in a complex      rule.  Throw-away rules are guided      rules that you never save.  You add      DSL elements to them, and you check to see if the rule validates.  You can even add a block for directly      entering LHS and RHS rule content, which is useful for testing DSLs.  If the validation fails, you can always delete      the rule, fix the problem, and try again.

• Always select the      dropdowns and populate the variables in a DSL that you have added to a      rule before you save the rule.  If      you don’t resolve the macro substitution values, the rule will not      generate successfully, and you may end up with a damaged rule.

• Always Validate every      rule before you save it.  If you      have added a bad DSL to the rule, and it caused the display of a part of      the rule to disappear, you are going to have a problem if you save the      rule.  Simply close the rule using      the “X” on the tab  (or click on      File : Delete if the rule is new and has never been saved), and the bad      stuff you added will just go away.       Once the rule is saved with the bad stuff in it, it may be      permanently damaged.

TIP:  Put a comment at the end of your DSLs which includes the name of the DSL, and references all of the Enumerations in the DSL.  Then, in the event of a problem, looking at a Source | View Source on a Guided Rule which has this comment imbedded in the source code, will show where you have a bad DSL or a missing Enumeration.  For Example:

...

TIP:  You can look for Enumerations all in one place by opening the package and clicking on the Edit tab.  Then select the URL for package source, and save the source to an editor such as Notepad++.  You can then use the search facilities in the editor to look for the Enumeration names.  If you followed the previous TIP about putting a comment in the DSL with the name of the DSL, you will know exactly which DSL is referencing the Enumeration.

6.     Recovering from a Single Damaged Rule

This information no longer seems to be pertinent in Guvnor 5.4, but is kept here “just in case.”

If the rule is damaged, but you can open it, you can do the following:

• Go to Source | View Source      and copy the contents of the generated rule.  NOTE      that any DSL generated information in the rule will have resolved the      macro elements to the extent possible.       If some of the macro elements were not resolved, look for missing      or renamed enumerations.

If you forgot to check the Validity of a rule before you saved it, and you can’t open it to fix it or delete/archive it, you may (or may not) first want to try to recover the contents of the rule by doing one of the following.

• Select the package and      click the Edit tab to show the configuration information.  Click on the “URL for package source”      and save the source to a file or an editor such as Notepad++.  This source file will contain all the      “DRL” source code in the package, including import statements, functions,      and all of the rules.  However, it      does not contain the source of the DSL files.  We have never had the DSL files lock and      fail to open, so this is not normally a problem.

• If you have installed      Drools in Eclipse and/or you are comfortable changing source code with a      text editor, you can try to fix the problem by manually updating the rule      source code.  Access the source code      file by connecting to Guvnor’s working version of the repository using      webdav (http://localhost:8080/drools-guvnor/org.drools.guvnor.Guvnor/webdav/  -- substitute the hostname and port of      your Guvnor installation, and add the package and filename that you need      to mess with, e.g.: globalarea/AssertionDsl.dsl      ).

If you were unable to fix the rule by this point, you then have two options to get rid of the damaged rule:

• Archive and Restore      the package.  Select the package,      and select File | Archive.  Go to      Administration | Archives and delete the damaged rule.  Restore the entire remaining      package.  Go to the package and      recreate the rule, fixing the bad DSL or Enumeration before you save the new      rule.

• The Nuclear option:  import a backup of the repository.  Go to Administration : Import – Export,      and import your most recent backup (Guvnor is nice enough to number      them).  NOTE:  this will destroy all the work you have      done since you exported the backup.       You did backup frequently, didn’t you?  J

7.     Recovering from an Inconsistent Package

I haven’t seen this happen in Guvnor 5.4.  But if it does, here are some things to try.

...

In the worst cases, your only choice is the nuclear option.  This will lose all of the work you have done in all packages since you last made a useable backup.  Which option you choose will partly depend on how recently you created a backup.  Having a recent backup is always a good thing…  J

8.     Recovering from Archived Global Area

It was impossible to recover from an archived global area in Guvnor 5.3, but is relatively simple to do in Guvnor 5.4.  Unlike Guvnor 5.3, Guvnor 5.4 archives the assets in the Global Area, but not the Global Area itself.  Simply go to Administration | Archive, and restore the assets.

9.     Recovering from Assets that Appear in Wrong Package

This will still sometimes happen in Guvnor 5.4, and if it does, here is what I found that sometimes would resolve it in Guvnor 5.3:

...

Another technique to fix the problem is to manually update the asset using a text editor or Eclipse.  Access the source code file by connecting to Guvnor’s working version of the repository using webdav (http://localhost:8080/drools-guvnor/org.drools.guvnor.Guvnor/webdav/  -- substitute the hostname and port of your Guvnor installation, and add the package and filename that you need to mess with, e.g.: globalarea/AssertionDsl.dsl ).

10.

...

     Recovering from Unintended Refresh

Unsaved changes are gone.  There is no recovery.

11.

...

     Recovering from Non-Functioning Enumerations

Remove all comments from the Enumeration file.
 

II.               Best Practices for Writing DSLs

...

V.                 Common Patterns for Creating Responses

A.     Write me…

asdf

Change Log