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