...
- 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. - 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.
There are certain cases where a Save and Close does not work, such as when you have just imported a new version of your data Model. In that particular instance it is best to close the screen for uploading a new model (after you have clicked the “Upload” button), validate and build the package, and chose “Save” from the File menu for the entire package.
If there are errors shown at this point (and you didn’t have errors before importing the new model), the most common problem is that your imported model is missing items (or has renamed them) that were in the previous model. Guvnor does not regenerate your “Configuration: Imported types” and “globals” when you import a new model. The most it will do is add new types and globals to their respective lists. Items you dropped from the model will still show in the list unless you remove them.
If you are working with complicated models that contain a large number of types, you may find it useful to click the “advanced view” of the configuration, then copy the contents and paste them into an external text file. Once you have the external text file, sort it, and save it with your project.
This makes it much easier to find the import statements that have been renamed or deprecated, and to remove them. Guvnor will happily allow you to paste the sorted list into the “advanced configuration”, and will keep it in the order you created. Any renamed or new types will be added to the end of the list after you import an updated model, and you can then cut and paste them into sorted locations in the list as well.
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. 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:Fancy Bullets - 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
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!Fancy Bullets - 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!
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…
The primary method I found in Guvnor 5.3 to damage a Guided Rule was to change a dependency, such as renaming or removing an Enumeration that is referenced in a DSL, and then adding the DSL to the Guided Rule. You could also damage a rule by making changes to a DSL without testing them, and updating the rule with the broken changes.
You can avoid ever having damaged rules by following this advice:Fancy Bullets - 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:
...
...
Note that the two comments highlighted above (one at the end of the [when] clause, and the other at the end of the [then] clause) will show in the generated source code, and the macro replacement of the DSL will include the selected drop-down value of the Enumeration named “VMRTemplateConcept.determinationMethodCode”. If the displayed source simply shows X=={X}, then the enumeration was not selected, or there was no Enumeration list by that name.
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.
...
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:Fancy Bullets - 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.Fancy Bullets 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:
Fancy Bullets 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?
...
...
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 some cases you can recover by doing the Archive and Restore technique described above. This is the most desirable approach, because it doesn’t lose any of your work.
In most other cases you can recover from one damaged package among a long list of packages by archiving and deleting the damaged package, and then recreating it from scratch. You may want to use the technique described above to save the source code for the package first, because once you delete the package, you will lose everything in it.
If you know what asset is damaged within the package, you can try to fix the problem by manually updating 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 ).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…
...
...
- 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.
...
- 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:
If you have created an Enumeration, for example, that has somehow appeared in other packages where it doesn’t belong, one fix is to archive and delete the Asset, close all packages, and then recreate the Asset in the correct package.
...
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 ).
...
- Recovering from Unintended Refresh
Unsaved changes are gone. There is no recovery.
...
- Recovering from Non-Functioning Enumerations
Remove all comments from the Enumeration file.
Best Practices for Writing DSLs
...