I have written many articles about the various error codes I have come across in drivers. I highly recommend everyone try this. When you are working with a driver all sorts of issues pop up. Keep a text editor open, copy and paste the error into the file, and then try to leave a note about the issue, and when you fix it, pop in a trace of a working item. Then you get an article to submit easy-peasy. Also, everyone who encounters the error after you and pastes the message into Google will find your nice description.
My previous error code articles can be found here (I probably missed some):
Recently I started working with the Multi-Domain Active Directory driver, and thus began collecting error messages. Seems like I have enough now to start releasing articles based upon them.
The first one was interesting. I deployed the packaged driver, and out of the box it started failing to start. Now as it turns out there were three error looking messages here, but only two were relevant. The middle message about being unable to retrieve application schema is not an error per se, so much as it is a warning. The other errors meant the driver failed to communicate, thus no schema could be retrieved. Fix those, this will likely resolve itself.
[04/04/16 14:38:50.411]:MDAD ST:
DirXML Log Event -------------------
Message: Configuration Error for connection at position 0:
Connection object mising at DXMLMADDriver.SPDriverCommon.createConnectionObjects(XmlDocument initParameters)
[04/04/16 14:38:50.415]:MDAD ST:
DirXML Log Event -------------------
Message: Code(-8001) Unable to retrieve application schema.
[04/04/16 14:38:50.688]:MDAD ST:
DirXML Log Event -------------------
Message: Code(-9124) Error in vnd.nds.stream://CORP-IDMDEV/acme/system/idm/dset/MDAD/Subscriber/NETQMADENTEX-sub-ctp-PermissionAttributesCaching#XmlData:339 : Element 'token-map-source-col' not allowed in 'token-map-source-col'.
The first error I will come back to, since I initially focused on the more obvious third error. This seemed to be complaining that there was some DirXML Script, which I had never seen before 'token-map-source-col' was not allowed under the token-map element. This was new as I was pretty sure I was familiar with the Map token, in fact I kind of like it and am a big fan, so much so I had written several articles about it:
If you are not aware, the error message has some very useful information:
Code(-9124) Error in vnd.nds.stream://CORP-IDMDEV/acme/system/idm/dset/MDAD/Subscriber/NETQMADENTEX-sub-ctp-PermissionAttributesCaching#XmlData:339
The error 9124 is useful, since you can look it up here: https://www.novell.com/support/kb/doc.php?id=7008882
and see it means "E_ELEMENT_NOT_ALLOWED -9124" which is about what the rest of the message says. But then it gives the path to the error, first by the full DN of the object with the error, the policy object named NETQMADENTEX-sub-ctp-PermissionAttributesCaching in the Subscriber channel. From the name I know this is part of the PCRS (Permission Collection and Reconciliation Service) code, which is a bit more complex than I would personally like. But the neat bit is the very last part:
Line 339 is part of this complete section:
To read that, they are setting an XML attribute named resource, inside the operation-data/permission node. But specifically the last permission node they added. If you do not specify the last() then it gets added to all of them, which defeats the purpose. Thus a would be the outcome.
The data for the resource attribute is coming from a mapping table. The entName local variable is passed into the mapping as the source data to look in the entitlementName column, to return the resouceDN column.
But wait, what is this stuff:
This is all new, and this is beginning at line 339 So what is the token-map-source-col? Did they add a new feature to the engine that I missed. After all, I maintain a book on engine tokens and a new one should be something I am interested in knowing about. First thing I did was look at the DTD for DirXML Script which is available here: https://www.netiq.com/documentation/identity-manager-developer/dtd-documentation/dirxmlscript/
I like this top page since it has a nice summary of the new things added in each revision of the engine. This as you can imagine makes keeping track of changes much easier for me. Alas, nothing about this token in the 45 or 4.5.2 sections. In this case, I started nagging people I knew to find out the answer.
Turns out they silently added this in the 4.5.2 engine patch and did not update the documentation to match, so one day they will update that page.
Similarly if you look at the page for token-map: https://www.netiq.com/documentation/identity-manager-developer/dtd-documentation/dirxmlscript/token-map.html
you will see that the new XML element is not mentioned.
After badgering some friends I found out that for the PCRS code, they needed the ability to look up data in a mapping table based on 2 criteria. I.e. Two (or more) source columns. The people in the IDC working on the PCRS project are also folk who get to work on the engine. Sometimes they solve a problem using an external Java class, like they did in the init-idm-resources.jar file that comes with IDM 4.5 and has some useful Java functions you can call. Sometimes they just add the feature they need to the engine, like in this case.
The idea here is that there is a mapping table, named EntitlementLLIDMapping that has three columns. It has the usual entitlementName column, and the resourceDN that maps to, but there is a third column, which is the Active Directory domain. That is, in this driver, you can have a Group or UserAccount entitlement to the driver, but it is specific to one of the many domains in the forest. Thus to know which Resource to map an entitlement to, from this table, you also need to know look at the domain name. They call it LLID which I have yet to figure out what the acronym is for, but it does not really matter.
Thus in the engine they added a new element under the token-map, where you specify the extra source columns you are looking with. The token-map gets a new XML attribute, type, that can have AND or OR as values. Thus you can logically AND the values passed into the table, or OR them. Apparently you can pass in many such extra source columns if you needed it. With the ability to do OR lookups, that may make for much more interesting use of this token in the future.
The token-map-source-col has a name XML attribute which is used specify the name of the extra column, and then nested under it, are all the usual elements you can use to provide a string as the value.
Before I understood this, I was running IDM 4.5 since I was having trouble getting IDM installed on Red Hat 7 so I had gone back to 4.5 to see if the 4.5.3 patch had broken it (No) but had not gone back to 4.5.3. Once I did it started working since this was added in the 4.5.2 patch which the 4.5.3 includes.
In order to get the driver working I tried disabling this action where ever it occurs. Turns out they use it about 8 times in the MDAD driver in 4 different policies. Once I patched to 4.5.2 I was able to re enable them and all was well.
I am told the DTD documentation will be updated with new information and I look forward to better understanding what happens here and what the possible options look like. Since I started writing this, they did update the DTD documentation which is nice to see. Complain complain complain seems like all I ever do sometimes, nice to see it get some results.
The next issue with this driver that is tricky is that adding a new driver requires a specific behavior that no other driver requires (that I am aware of). In Designer, you cannot right click on the driver set, select New Driver, then pick the Multi Domain AD driver out of the list. Instead you MUST use the palette on the side of Designer, which I honestly otherwise never use to drag and drop the driver. I find the palette an annoyance and minimize it when I start Designer. It is possible that the Linux/Unix fan out or the AS400 fan out need to be installed via the palette since they to have an additional too for managing the Census and the fanned out servers. But I have not tried one of those in a long time to know. Oddly I went to check and cannot find them in my Designer, which makes me wonder if I missed something in the last release related to these drivers.
However, there is a tool that is delivered when you use the palette and not just the base package that allows you to specify the Forest and Domains. It connects to the Global Catalog server and is able to resolve the Domain Controllers in the domains, the various domains themselves, and the Exchange servers with MDBs available. What is confusing as well is that the tool is available in the right click context menu as "Multi Domain Active Directory configuration" but only on the Driver icon object at the end of the driver line. This option is NOT available when you click on the driver line itself. This confused me a bit in the first release of this driver, since I always use the driver line. It was only because of this that I even found that on the Driver icon object, there is a Driver sub menu with all the options available on the driver line. However, since that is one extra click, I would prefer to use the driver line right click menu instead. I tried pushing the Designer developers to consider working with a mouse mileage meter, while in Designer and see if there were options to make the UI less distance intensive. Alas, no luck on that complaint yet. But I shall persist!
This allows you to build a series of DirXML-Resource objects that have the DirXML-ContentType of application/vnd.novell.dirxml.fanout-ext xml and contain data that looks something like this:
These objects get pushed into eDirectory in the Identity Vault. You have to Deploy them first. Then in the driver configuration, there is configuration setting that is a structured GCV that lets you add as many connection objects as you have, which is done by browsing the Identity Vault to find the DN of the object (Thus why you need to deploy them before this step). The key step here is that you specify a password for each connection that is stored as a named password, thus adding the final piece of information the driver will need to connect.
Once you start, the engine will build the driver configuration that it sends to the shim on startup with the structured GCV referencing the various configurations you enabled.
If you are missing any of the configurations or not linked properly or missing a named password you will get errors at startup which I will review in the next section of this series on the Multi Domain Active Directory driver errors.