Adding IDM4 Reporting support to pre-IDM4 drivers - Part 3

Novell Identity Manager 4 has a bunch of new features. You can read what I think of them in this series of articles:

Based on requests from customers, the feature most are interested in is Reporting. That is, most of our customers interested in upgrading to IDM4 are interested in it for the new Reporting features.

You can read the first two parts of this discussion at the link for more discussion on what is going on:

I believe there are at least four things needed to support Reporting in an existing driver, based on looking at what is needed in a Packaged driver. I am still trying to fully validate that I did not miss anything, but so far so good.

There are 3 Policy objects that need to be added:

  • NOVLDATACOLL-itp-DataCollectionQuerySupport

  • NOVLDATACOLL-smp-SkipSchemaMapping

  • NOVLMSINFO-itp-InitManageSystemInfo

There is a Global Configuration Variable (GCV) Object needed, named MSysInfo, as a child of the driver object.

I worked through the various rules in the previous articles and the GCV that is needed.

A quick reminder that the Managed System Gateway driver is going to reach across to each driver in its driver set, and read back the MSysInfo object and parse out the GCV's of interest to it, to use in responding to queries from the Reporting server.

You can read more about how that works at a driver level in my series on the Managed System Gateway Driver:

As I attempted to be sure that I got everything I decided to see if the release notes for the packages had any tidbits hidden in them. Getting to the readme for a Package is sort of tricky. You need to have a Designer project, that does not have the package yet in the project's Package Catalog, but you have downloaded it from Novell. In that case, as you go to import Packages into the Catalog there is a button to show the Readme, and it pops open a window on the right side, kind of like how Help sometimes pops up in Designer.

There were three bugs referenced, and when I tracked them down in Novell's Bugzilla two were inconsequential, and one was related to the Data Collection Service driver itself, adding some new Schema. But I initially thought it was for one of the DCS packages in the various drivers, so I spent some time hunting it down to be complete.

Along the way, I found that actually the Managed System Gateway driver also has 4 Prompt Resources in the package for the Active Directory driver that I did not really address yet. In Packages, there are many types of resources available, since there are all sorts of things you might want to include in a Package, that is not a Policy, a filter, or a GCV. The usual villians are available, Text, XML, Entitlements, Mapping tables (anything that is of type DirXML-Resource object class, and really any of the DirXML-ContentType values that are available). Here is the list as I see it:

  • Mapping Tables

  • Single Sign On (SSO) Credential Repository

  • Single Sign On (SSO) Application

  • Raw Text

  • Raw XML

  • ECMA Script object

  • DS Object

  • Package Prompt (new for IDM 4 Packages)

  • Filter Extension (new for IDM 4 Packages)

  • Entitlement Configuration

Anyway, one of interest here is the Package Prompt resource, and it has a couple of interesting features. It is designed to allow the person building the Package to update, change, or keep the same, GCV's or Driver configuration values. This is quite an interesting concept, and it uses XSLT to transform the current values, showing them in the fields when you use it in an Upgrade, differently than when you use them in a full install. Suffice to say it is kind of poorly (not at all?) documented. The nice part is that there is some sample XSLT with comments inline to try and somewhat explain what is being done. Otherwise it would be really hard to figure out.

There are four such Prompt Resource objects in the AD drivers Managed System Gateway.

  • NOVLADMSINFO-GeneralINformationPrompts

  • NOVLADMSINFO-SystemClassificationPrompts

  • NOVLADMSINFO-OwnershipPrompts

  • NOVLADMSINFO-UpgradeSettings

I went through all four Prompt Resources, and they all target the same thing, the MSysInfo object, and are designed to keep the existing values as set during an upgrade or downgrade of a package, and prompt you for values during a fresh install of a driver.

Thus although they look like quite a bit of content, they effectively do not matter to us directly. If you were to try and install an Active Directory driver that included this package, you would actually get four different prompt pages for these settings. What is interesting is that they all reside in the same GCV object (the infamous MSysInfo) and all the data is going to one location, yet it is handled 4 times in pieces. I imagine there is some backstory in terms of how development of this component proceeded that led us to this point.

Now, having explained WHAT is happening in the drivers with the policies and why you need the various policies we get back to the question of HOW do you add these to your IDM 3.6.1 drivers that you have upgraded to run with an IDM 4 engine.

That is, my description is nice, but how to take advantage of this knowledge and actually use it is much more useful.

Since you must have upgraded to an IDM 4 engine, you are probably using Designer 4 now as well. (PS: Get Designer 4.01 from the IDM 4 SP1 release, since it has some really major memory leak and performance fixes that make a really big deal in performance).

The content you need is all available in Designer 4. Once you install it, and open a project for the first time, you will be asked if you want to check for Package updates. I would recommend disabling the annoying check for Designer updates but keep the check for Package updates as Designer has only ever seen 2 or 3 updates via this approach, but already since IDM 4 was released we have seen dozens of packages updated.

Then I would NOT yet import the Packages into the projects Package Catalog until you need them, since the clutter up the workspace, which makes backing it up harder, etc. Also I believe they might make it into your Subversion repository if the project has version control enabled. The only reason to possibly consider avoiding it would be due to the size it makes your workspace, and the number of files. I went to free some disk space and zipped up some older workspaces, and found I had two hundred thousand files in those workspaces, which seems like a bit much. (Also Windows is lousy when manipulating hundreds of thousands of small files)

So start a fresh project, I call mine Scratchpad, and import the Packages available into the Package Catalog of that project. Then add an IDM 4 Identity Vault into it. Now you could use your existing project and just add a new identity vault into it, but it is nicer if you can keep things clean.

Once you have an Identity Vault set at IDM 4 level, you can start importing drivers from the Packages, and then you might as well just add a generic Active Directory driver, accept all the possible packages, and you will see the various things I have been talking about all along.

Then you can open up each of the three rules discussed, and in the XML Source view (tab along the bottom) you can copy the entire XML into a new policy object in your existing IDM 3.6.1 driver. Rinse and repeat for the other two.

You will need to make an MSysInfo GCV object at the Driver level to paste the XML into, the object type in the New menu is Global Configuration. The names I provided for all the various objects referenced in this article are from the Active Directory driver and might be slightly different in another driver, mostly in how the Package is named. The Data Collection Package is actually in the Common grouping and can be applied to any package, but the Managed System Gateway is specific to the driver, since there is a hard coded string in the policy that auto updates the GCV object with the category of the driver. AD for Active Directory, and I did not yet check what other values are used in other drivers.

Then after I wrote this down I realized I was being dumb.

Your engine is IDM 4 and you configurations are legacy, but I need to tell you how to add a bunch of policies and settings to a driver. That sounds like something I should remember. That sounds a lot like a Package.

So for the heck of it I made a Package with all these policies in one. Along the way I learned something amusing. In the first article you may remember that I discussed a policy in the Schema Map that is linked in twice. It is linked before the Schema Map rule, to change the attribute names so the filter does not apply to Data Collection driver generated queries. Then it is linked in AFTER the Schema Map to reset the results, which ends up with the Data Collection driver query returning its results in the applications native schema namespace.

Well if you look at the Novell provided Package for this, there is a tab on this Policy in the Package Catalog called Linkage. This is where you are supposed to specify in the Package where to insert this policy. There are several approaches, but the key is the Novell provided Linkage setting cheated! They used two values! If you try and do this yourself you will find out that Designer only supports a single linkage being set. Must be nice owning the source code.

Anyway, I actually tracked down the file in the Workspace file system that stores the XML for the Package element, and I can see how to change it to add a second linkage value. It is just some XML that is HTML encoded (Less than signs escaped to <r; and so on) and easy enough to add a second one. But those darn sneaky guys decided to add a checksum to every field and I do not know how to generate a new checksum so that Designer will not just reject my change out of hand.

So I had to do it the ugly way and just include the same exact policy twice. Once with a Linkage, using wieght for placement of 100 (so that it goes first) and then I copied that to a new name, and added it a second time to the Package with a Linkage using wieght of 900 so that it ends up at the end of the list.

I will attach a 0.0.1 build of my Package with this article and let me know what you think. That ought to be the easiest way to do it.

I see some enhancements I want to do. I want to find out all the various driver type values used, dump them into a List GCV instead of hardcoding it in the policy so that this one Package would work better for all driver types.

I think I did the Prompt handling right, but am not completely certain that I did. The good news is you can easily go back and set the 9 GCV's that it uses by hand. They are all up to you to provide anyway as they are just descriptive text to show up in reports later.

This is actually my first actual Package for distribution so let me know if I made any mistakes so I can update it. (The joys of Packages right? If I goof it up, and figure out how to fix it, I will just make an 0.0.2 version and it is easy for people to upgrade.)

I want to rewrite some of the policies since they do some things I think could be done better or nicer, but they should work fine as is for a 0.0.1 release.

Packages are really the future in IDM and it is a good excuse to start using them. The practice of building a package for this shows that it is really not that hard if you start with a simple task and keep the scope manageable. I think we will see interesting things develop as Novell and their partners get better and more experienced with using Packages and as the options expand.

If you want to read more about Packages feel free to look at my series of articles on the topic:

As I was getting the Package finalized, I even found an issue with how Linkage works, so looks like it will be a 0.0.2 build.

Download the attached JAR file (I may ZIP it to make it easier on browsers and servers to deal with) and right click on your Package Catalog in a project. Then you will see any Packages that Designer has downloaded, but have not yet been imported into this Project, and you can click the Browse button to pick a file in the file system.

Once you do that, go to your existing driver, (Right now this is only for an AD driver, but there is only one string that needs to be changed in the middle of the rule that updates the MSysInfo GCV object to make it work for other drivers) and on the Properties page, select Packages, and you can now add this Reporting For Older Drivers package to your AD driver.

Give it a shot and let me know how it works out! I have not heavily tested this, but I think it should work. If you find I missed something that would be very helpful!


How To-Best Practice
Comment List
  • I know there are two issues in the Package attached:
    1) The list of system names is actually hard coded to AD. This is because I was too lazy to go install every single driver type to go find the entire list of possible names, and then make them into a setting. If anyone feels like volunteering to do that, I can easily add them once i know the data.

    2) I should have copied the Novell package prompts as well for the GCV objects, not just the objects.

    I will try and find some time to update it. Beauty of packages though, once I do, everyone can easily use it! Just upgrade! Yay! I love packages.

    (Thanks Tim E for noticing.)