What do the various IDM driver object attributes represent Part 3:

In part 1 of this series What do the various IDM driver object attributes represent - Part 1 I discussed some of the attributes that are found on the DirXML-Driver object when you look at it raw in the directory. In the first article I covered the following attributes:

DirXML-Policies
DirXML-NextTransformation
DirXML-ACT2
DirXML-ApplicationSchema
DirXML-ConfigManifest
DirXML-ConfigValues
DirXML-Filter

In part 2 of this series What do the various IDM driver object attributes represent - Part 2 I covered the following attributes:
DirXML-DriverImage
DirXML-DriverStartOption
DirXML-DriverStorage
DirXML-DriverTraceLevel
     DirXML-LogEvents
     DirXML-LogLimit
     DirXML-TraceFile
     DirXML-TraceFileEncoding
     DirXML-TraceLevel
     DirXML-TraceName
     DirXML-TraceSizeLimit

The Trace related attributes all sort of fell out as part of the discussion around the first one, since they pretty much work together as a set of values.

In this article I would like to cover the following attributes:
DirXML-DriverID
DirXML-DriverVersion
DirXML-EngineControlValues
DirXML-InputTransform
     DirXML-OutputTransform
     DirXML-MappingRule
DirXML-JavaModule
DirXML-NamedPasswords


DirXML-DriverID

I cannot find this attribute in use on any of my projects, so I assume this is a holdover from earlier Identity Manager versions.

DirXML-DriverVersion

This stores the version of the driver. The numbers you might see are all over the place. For example the Active Directory driver is still 3.5.x even the version in IDM 4 (latest as I write this is 3.5.13). Which is actually a good thing as they use the same driver shim (addriver.dll) for IDM 3.5, 3.6, and 4.0 instances and the licensing credential does not change either. The User Application drivers usually show a very different version number. For example an IDM 3.5 Provisioning module User Application driver shows a version of 0.20080709.164851. Other drivers like eDirectory or Loopback, show in the format of 3.6.13.5349 as an example. Usually I just look at the trace, and events on the Subscriber channel will have an XML attribute called version in the <nds> node, whereas events on the Publisher channel will show the shim version.

DirXML-EngineControlValues

Engine Control Values (ECV) are sort of an odd set of values. When you import a driver into your project, this attribute is usually not populated. I believe it gets populated one of the first times you actually start the driver. I have never seen this happen in trace, and I imagine if it is, it may be traced at a higher level than I have ever looked. (For more about DSTrace see the previous article and the many links to discussions about DSTrace). However, the values available have changed as the engine version changes. That is the ECV's available in Identity Manager 3.01 are included in IDM 3.5's ECV's but 3.5 has some added.

I have not bothered to keep track to see what ECV's came with which IDM version, but if someone has, please post it as I would be quite interested in reading it. I know of several ECV's that are important and that I manipulate regularly.

dirxml.engine.retry-interval
dirxml.engine.max-migrate-app-count
dirxml.engine.qualified-dn-values

dirxml.engine.retry-interval:

This ECV controls how long the driver will wait, when it gets a <status> event with a level = 'retry' in it. This is common in the case of a rename event being sent to eDirectory. When a rename or move event occurs, obituary processing becomes involved (Also in Delete events, but for deletes the Inhibit Move obituary is usually not involved). Obituaries at some points in eDirectory's history have been problematic, but mostly now, they work just fine. They do however take finite time to process and clear. The cases of rename, move, and delete trigger the obituary process, since you need to be certain that the deleted (renamed or moved) object is propagated to all the replica holders. Imagine what would happen with out this process. Say you have three replicas of a partition and the delete occurs on Replica A, but the server holding Replica B is down for maintenance. When Replica B is returned to service and connectivity, then the deleted object might reappear as it missed the delete event. (Yes the delete should be queued, but you get the idea.). Thus the obituary process ensures that all the replica holders agree about the special case events before considering them completed.

Well move events happen to be tricky little things, especially when you cross a partition boundary. There are many steps involved, and until they complete it blocks other move or rename events through the use of a Inhibit Move obituary.

Thus if you sent a move event into an eDirectory driver, and soon after tried to do a rename or another move, the engine would return a -637 error Previous Move in Progress, with a retry status document.

Thus the driver will wait the ECV defined amount of seconds before trying to send the event again. Sometimes 30 seconds (the default value) is too long, and other times too short, depending on the environment, and thus needs to be tweaked.

dirxml.engine.max-migrate-app-count

This ECV is quite interesting. If your driver supports query-ex, that is paged queries, then when you do a migrate from Identity Vault operation in iManager, the query will actually be converted to a query-ex, with a max-results set to the ECV specified value.

I ran into this when I was working on a SOAP driver to connect to Salesforce.com, which you can read more about in this series of articles:

• Getting Started Building a SOAP Driver for IDM - Part 1

• Getting Started Building a SOAP Driver for IDM - Part 2

• Getting Started Building a SOAP Driver for IDM - Part 3

• Getting Started Building a SOAP Driver for IDM - Part 4

• Getting Started Building a SOAP Driver for IDM - Part 5

• Getting Started Building a SOAP Driver for IDM - Part 6

• Getting Started Building a SOAP Driver for IDM - Part 7

• Getting Started Building a SOAP Driver for IDM - Part 8

• Getting Started Building a SOAP Driver for IDM - Part 9

In that case, the default was 200 and I had changed it to 2000 and it was sending back huge node sets that were taking 20 minutes to process, even with trace turned down. This made it look like the driver was hung. That was a fun one to debug. In the end there, on top of getting the size down, I also was able to tailor the migrate query to something smarter that returned far fewer attributes so that 20 minute pause was cut down to about 2 minutes as the SOAP document was converted to XDS.

Mostly this is related to the amount of Java heap you have, since a migrate of every object at once, would probably wipe out all your memory since they all get processed in the same basic event and eat up memory together. Thus if your connected system can process query-ex then paging the results into some smaller number can be very effective at keeping memory usage under control.

You can also use query-ex in your own policy. If you use the Query token, you will see there is a Max Results item you can provide a value for. It turns out this is slightly mislabeled as you might expect it to ONLY return the max results value. I.e. Only return ,e 5 out of all possible values. However it returns the specified number of values, in each page.

Your driver has to support it, (eDirectory does) and you will see during driver startup that the __driver_identification_query__ will go by, and its response will include whether the driver shim supports query-ex or not. In the case of the SOAP driver, I had to open a support request, and get the functionality to support query-ex IF you code for it, into the SOAP driver which has been added to the latest patches for the SOAP driver shim.

dirxml.engine.qualified-dn-values

This controls a subtle change in how eDirectory returns data when queried. When you generate a <query> event, the response is an <instance> document that has a couple of XML attributes in it. There are several possible but src-dn is the most interesting one for us. However, src-dn is returned in backslash notation. That is, com\acme\User\geoffc as the path to my user object in the directory. The ParseDN token can use that for some tasks, but not for all. Specifically, if you want to convert the DN to LDAP format, you cannot, as there is information missing in backslash notation that LDAP format needs. That is, the type of each node along the way. Is that com a cn=com, o=com, dc=com or something else? I think it would be great if ParseDN was made smart enough to go out and figure it out for you, but until then, the answer is the ECV. When enabled, (it is now on by default) events will come back with a new XML attribute qualified-src-dn which is in a strange format called qualified slash. This is then easily converted by ParseDN to LDAP format. Qualifed slash looks something like dc=com/dc=acme/ou=Users/uid=geoffc which now has sufficient information for ParseDN to work on it. You can read more about ParseDN in these articles:

• Examples of using the ParseDN Token in Identity Manager

• Parse DN Custom DN Delimiter Example

There are other ECV's available, but these are the most interesting to me. (Or at least ones I have at least changed or contemplated changing).


DirXML-InputTransform
     DirXML-OutputTransform
     DirXML-MappingRule

In the first article in the series, I discussed the DirXML-Policies attribute and how it deprecated the old policy model where the Driver object had DN reference attributes pointing at DirXML-Rule objects for the DirXML-InputTransform, DirXML-OutputTransform, DirXML-MappingRule and then used the DirXML-NextTransformation to link additional policy objects into a chain of policies.

These are the deprecated attributes. The DirXML-Subscriber and DirXML-Publisher objects have DirXML-EventTransformationRule, DirXML-MatchingRule, DirXML-Create, DirXML-PlacementRule , and DirXML-CommandTransformationRule attributes that are also deprecated in favour of the new Policy linkage model.

The new model breaks out of the linked list approach, and allows for any policy object by itself to be anywhere in the driver. This means Library objects work, as we did for a couple of clients where we make a template driver that is reused. It has no policy of its own, under the driver object, every policy is linked in from a shared library. This works well when you need to connect many many systems that are basically the same without customizing each driver. It gets tricky as you have to handle the various use cases through GCV's but it is quite doable.

DirXML-JavaModule

This attribute holds the name of the Java module of the driver. Each driver shim has a Java class that is called to start the driver. There is a list in the documentation of the various values. Normally you do not care since most driver configuration files and now Packages will include the information needed.

However an example of where you might care, is the Remedy driver uses different Java classes depending on the version of Remedy your system is running. Thus the driver ships with one value in the configuration, but you are as likely as not to have to change the value if you have a different Remedy system running in your environment.

DirXML-NamedPasswords

Named password were a great innovation when they arrived in IDM 3 I think. Driver objects come with three stored passwords. The Remote Loader, Driver Object, and Application password. These are stored encrypted and the driver can retrieve them as needed. However many other passwords might be useful. For example, in the case of Lotus Notes (Domino server) the certifier files, needed when signing a users private key in a container are always password protected. The way it works in Domino is that each OU object is its own Certifier. You can imagine it as a PKI chain, where each OU is actually a Certificate authority (though technically a Sub-CA from the top of the system).

Thus if you have many containers you are provisioning users into in Domino, you might need a different password for each one. Now storing them clear text in the policy is a terrible idea, as the XML that makes up the policy is just a plain attribute (Base 64 encoded but so many tools decode it by default (ConsoleOne, some LDAP browsers) that it is basically plain text), which potentially people can read depending on the rights assigned in the tree.

With the advent of Named Passwords, you can define them (At the driver and driver set level) and the passwords will be securely stored. To get access to them, there is a Named Password token that can be used, and there is a GCV type, called password-ref that acts almost the same way. When you define a GCV of type password-ref, you specify the NAME of the Named Password. Thus when it comes time to set a password-ref GCV that sets the named password value. When you use the GCV you get the named password returned. This makes for a much easier way of handling passwords in policy.