If you have read any of my other articles you will know that I am a very big proponent of using the Comments fields wherever you can. That means when you write a rule in Identity Manager you should explain what the rule is doing, more importantly why you are doing it, and most importantly what you tried before that did not work.

When working on a large project or with other people, you usually take the simple elegant approach to a problem. Then after testing you find out that you need a slightly more complex approach to actually work in your environment. That is all great.

Then a month later, during which you worked on many other things, you come back to troubleshoot, and you track it down to this rule we are talking about, and you look at it again with fresh eyes. Your first comment is, why ever would I do something in such a convoluted way. There is a much simpler approach. So you change it to what you originally started with and test, find out the same issues, work through the troubleshooting process, and end up either back where you started this time around, or with minor tweaks.

Well you just lost the value of all that testing and troubleshooting you did the first time around and reproduced it. If you do not remember doing it, then that is Vuja De! De Javu is when you could swear this event has happened before. Vuja De is when you have no memory of this event, but clearly it happened the exact same way before!

As a consequence, I get very verbose in my Comments tag for rules in Identity Manager. There appears to be no real limit (well I guess however big a Stream syntax attribute can be since it is all stored in the XMLData attribute, and that is a Stream file syntax attribute) to how much commentary you can add, so the more the merrier.

The editor in Policy Builder in Designer and iManager tools are smart enough that if you insert a character into the comment field that would break the XML to escape in the proper fashion, so if you look at how the data is actually stored in the XMLData attribute, you will see it replace a less than sign (<) with < and so on for all the various specail characters in XML.

What is amusing that I just ran into recently, is what happens if you try to discuss a GCV and you show sample code in the comment. I was talking about a generic case, and I mentioned in the Comment field that I use ~GCV~ to represent a GCV called GCV.

Well the driver refused to load after I saved that change, since there was no GCV defined anywhere, called GCV. Oops. It looks like the engine on load of the driver tried to replace the ~GCV~ in the comments with the value of GCV as if it were part of a rule somewhere.

This is probably a bit of a bug, but trivial, and funny, to work around.

This is easier to understand what the issue is if you know how the engine handles the ~GCVName~ syntax. At the time the driver loads, and it encounters a ~GCVName~ reference, it tries to do a replace of that value with the contents of the GCV as part of loading the driver. Thus if you change the value of a GCV, it needs a driver restart to take affect.

If it cannot find the GCV to replace the reference with, it throws a fatal error, which is what I ran into.

Now I need to track down what the correct escape sequence is to enter a tilde (~) character in the comments, try to get it declared a bug, or do what I just did, and change all such references from ~GCV~ to tilde-GCV-tilde in the comments, which is probably good enough.