...
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.
...
- 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.
...
- Possible to Add Invalid DSL to a Guided Rule
no longer an issue in 5.4
...
- Possible to Permanently Damage a Guided Rule
no longer an issue in 5.4
...
- Possible to put a Package into Inconsistent State
no longer an issue in 5.4
...
- 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.
...
- 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.
...
- 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.
...
...
- 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.
...
- 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”).
...
- 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… J1.
- 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 |
|---|
|
...
|
...
- 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…
...
Our first effort might look like this (and it is all on one logical line):
| Pre |
|---|
| ($encTypeConcept : EncounterTypeConcept( openCdsConceptCode == "C44" ) and $encEvent : EncounterEvent( id == $encTypeConcept.conceptTargetId, subjectIsFocalPerson == true, encounterEventTime.high < evalTime )) |
If we then clean up the variable names (the elements beginning with “$”) to make them globally unique in a long and complex rule with many DSLs, this text might look like this (and it is still all on one line):
| Pre |
|---|
| ($PatientEncounterEventDsl_encounterConcept_OutpatientEncounter : EncounterTypeConcept(openCdsConceptCode == "C44") and EncounterEvent(id == $PatientEncounterEventDsl_encounterConcept_OutpatientEncounter.conceptTargetId, subjectIsFocalPerson == true, encounterEventTime.getHigh()< $evalTime )) |
This is now a working DSL, but it only knows how to do the one thing you hard-coded into it. You are going to do several more steps to turn this text into a very useful and re-useable DSL:
Write a clear plain-language statement of
what the DSL is supposed to describe, follow it by an equal-sign (“=”) and
place it in front of the text you copied from the sandbox rule. This might be something like
Pre Patient has previously had an outpatient encounter =
...
followed by the text of the rule that you wrote to implement this, as shown above.
...
Abstract out the concept
...
instances into enumerations that you identify by {X} – any variable name
...
surrounded by curly braces, and with some additional information that will
...
be demonstrated in examples below.
Also abstract out any quantities you might want to change into variables that you identify by {n} – any variable name surrounded by curly braces.
The left-hand side of the DSL has then become something like
Pre Patient has previously had a {X:ENUM:EncounterTypeConcept.openCdsConceptCode} = Replace the specific concept on the right-hand side of the = with the variable name[s] in curly braces, and you get this for the entire DSL:
...