Explaining GCVs - Part 1
If you have used Novell Identity Manager much, you probably have run across Global Configuration Values.
These are my personal favorite things in Identity Manager. Ok, in reality I have a list of personal favorites, but GCVs are pretty high up that list.
I have written a number of articles on the topic already, that you can read for more background:
- Using Global Configuration Values in XPATH
- How to GCVize a Driver, Part 1: Subscriber Channel
- How to GCVize a Driver - Part 2
- Discussing GCV's in Comments field in Identity Manager
I mention GCVs in many of my other articles in passing, and they are great. I thought an article dedicated to the fun things you can do with GCVs would be appropriate and entertaining.
First lets get some basics out of the way. There are a couple of key things to know that make them more powerful and are somewhat non obvious.
You can define a GCV at the Driver or Driver Set level. This is a pretty cool feature, as you can define a GCV, called allow-user-sync on the Driver Set, and set it to true. Then if any driver you want to disable it, you just add a same named GCV at the Driver level, and set a different value and it overrides the Driver Set value.
This is great because you can control a setting globally across many drivers, and yet still have the ability to handle exception cases. This really worked well for me, I had to build an Active Directory driver for a client, in a template format. and we had every rule in a Library, and controlled the fine tuning with GCVs. We had some basic standards, but on each item that mattered, some local site needed an exception. Additionally the client could not decide on some critical functionality, so we expected to have to switch things often.
Most of the configuration values were set at the Driver Set level, and when we needed an exception in a specific case, we set the override value at the Driver level. This let us use a single set of rules, and configurations, for many drivers, as many as we needed, and fine tune each one as needed.
Next up is some basic usage of GCVs in rules and policy. There are actually one two GCV related tokens. There is a Condition, if global configuration value, which can be the usual equality tests. Equal, not equal, less than, greater than and so on.
This is great because you can manage whether a rule fires or not by the use of this token. If global configuration allow-user-sync equal true, then do the rest of the rule. You can see many drivers that use this approach at the driver level. The new configurations from Novell released with Identity Manager 3.6.1 try to use this approach as well for the GCV idv.data.users which is written to the driver set by the first driver installed. This GCV is used for placement of users by default.
What is nice about this approach, is that if all of your drivers, have the same user container, then you are done. If one needs a different value set, say to scope it to a subset of users, just add the GCV to that specific driver with the proper DN value, and no code changes required.
There is a Global Configuration Value noun in Argument Builder, which is used when building strings for most string fields. This one lets you pick from a list of GCV's, showing both the name and the value. This is useful if you forget the exact name of the GCV, and have a couple if similar ones, but the values should be different.
As I was writing this, I was quite surprised that there were only two tokens in total that directly relate to GCV's. I was sure there were more. However, thats all they wrote!
In the upper right hand corner, is a teeny tiny widget, that is kind of sneaky. If you click on it, you get a Create new GCV on Driver window, which is great. However, if you hit the even tinier down arrow, you get a menu that says Create a GCV on the Driver, and the second entry is Create a GCV on the Driver Set.
This allows you to decide where you want the GCV to reside, depending on the scope you want it to have.
What is annoying is that anytime you are in the GCV picker, which is a great tool, you cannot edit any GCV nor the one you just created. If you create one, and realize you made a minor (or major) typo and want to correct it, you need to finish the rule, and you might be many many levels deep into a rule, and getting out could take quite a while. You would have to get all the way out, to be able to edit a GCV on the Driver or Driver Set. I submitted an Enhancement Request for it, using the RMS portal, at: http://www.novell.com/rms and we will see what comes of that.
When defining a GCV there are a number of possible types you can define. New with Identity Manager 3.6.1 and Designer 3.5, is a new GCV type, called Structured. This was added to handle the new fanout SAP UM drivers. But this GCV type can be really useful in other use cases as well. Basically it allows you to define a structured GCV, that is a GCV with several components (sort of like PATH or some of the other fun syntaxes in eDirectory) and set up a template for it. Then once defined there is a + icon where you can add a new instance of this structured GCV. In principle I suppose you could even make a template for a GCV with a single component, which would useful in and of itself.
The other types are pretty simple and obvious, things like String, Integer, Real, and Boolean. These are pretty much self explanatory. Each has its own little sets of caveats, fun little things. Then there are the more complex and interesting types. Password-Ref, DN, List, Enum, and Structured.
Obviously this is for String fields, and most times, you could use this for everything if you so desired. However, it is often more efficient or smarter to use the correct type. You get one extra option, to make it multi line, in case you have a large block of text to store. I have used this when I am trying to store an XML document to send to the srcCommandProcessor when I am trying to send an XML doc, rather than try and build it in Policy of XSLT. You can see an example of that in using Stored procedures in the JDBC driver in this article: http://www.novell.com/communities/node/2786/calling-stored-procedures-idm-jdbc-driver or in the SAP HR driver, to make a RELATIONSHIP query (which I still have to write an article about), or in the SOAP driver to cheat a little bit. There is really no difference in the storage, it just makes the display nicer.
When you select Integer, you limit the field to whole numbers, and you get a minimum and maximum value fields, to allow you to try and constrain people from entering invalid data. If your GCV should only hold numbers between 1-5, you could put limits on it easily in advance. I have never had to use this, but it is easy to imagine a case where you might need the functionality.
You can see the fields in the image above.
This is pretty much the same as Integer, but allows a decimal point as well. I am not sure there is really a hugely different use case between the two, but it is nice to have.
You can see the fields in the image above.
As you might imagine, this preformats the results to be true or false. By selecting Boolean, you do not have to build true or false options, the GCV picker widget for this type of GCV is set up for you, by the UI. This is a nice touch to have.
Not much to see so no image this time.
DN (Distinguished Name) is a very powerful GCV type. What really makes it shine is its use of the DNConverter functionality that the ParseDN token shares in common. You can read more about the ParseDN token in these articles:
With the DN type GCV, you can select a couple of things. The second (since it is simpler) is to just select the namespace in which the DN will be related too. The Application, or DirXML, which in this case, means the engine. That is, you can tell the GCV definition where to go look for the object reference, when someone uses the picker widget.
When you create a GCV of DN type, you get a magnifying glass picker icon, which is meant to denote a search for an object through the tree. This lets you pick the object via an eDirectory browser. The format that the value selected is represented is selected by the first option.
The first option is the DN type that the data should be stored in. You have all the options available in the ParseDN token, which is great. You can store it as slash notation (com\acme\users\jsmith) that Identity Manager uses as its natural storage format. You can select LDAP format, to store it as cn=jsmith, ou=users, o=acme, dc=com or the like. Or any of the various formats allowed by the ParseDN token, even Custom! Custom is a really cool feature, where you can write an 8 character string that describes your DN pattern, so that ParseDN can parse it. You can read more explaining how that definition string works in this article: Parse DN Custom DN Delimiter Example
This is an interesting type. There is a nice feature, I forget when it was introduced, called Named Passwords. These allow you to store password values, in an encrypted form, that the driver can recover on demand. There is a Named Password() noun token in Argument Builder that can pick up the value and provide it to your policies. There are lots of instances where you might need this. A classic example is in the Lotus Notes / Domino driver, when using multiple certifiers. In Lotus Domino, you can build an OU structure, but it is pretty different than what we are used to in eDirectory. For one thing, the only thing stored in the OU structure seems to be Users, since Groups when queried via LDAP (Notes can enable an LDAP server) appear in a flat namespace. It is pretty strange when you see it. But more critically, each OU is a Certifier, which you can consider similar to Certificate Authority or Sub-CA. That is, all objects under the OU is signed by the private key of the OU. Which is signed by the parent OU's Certifier, and so on.
Thus if you have a Lotus Domino system with three or four OU's (or 70 someodd like one client) then you actually have to give the driver access to the private keys of 3 or 4 (or 70+!!) certifier files. All certifier files are protected with passwords (Basically another version of the Notes ID file) and really, you do not want to hardcode all those passwords in policy. So using Stored Passwords is a much better and secure approach. It is encrypted much the same way that the Remote, Driver, and Application passwords are already stored in the driver object.
What is cool, is that when you add a GCV of this type, you get prompted to specify the name of the Named Password. Then when you go to 'set' the value of the GCV, you populate the Named Password, that was so named by the GCV. It is a really nice way to handle storing passwords in GCV values, but making it secure. This is basically is the Password GCV type, made secure. What will they think of next?
Oh I know, the next couple of GCV types, List, Enum, and Structured! Stay tuned for part two where I discuss these last three types, and some more fun stuff you can do in GCV's.
Part 2 of explaining GCVs
Discussing Structured GCVs