When you are working with Novell Identity Manager, you get to learn more than just the Identity Manager system and its components. You have to learn a fair bit about each of the connected systems you will be working with.

Each driver is a little bit different, as you can see from these articles. The first one discusses the different association values you might see in the third part of the DirXML-Association attribute:
Open Call - IDM Association Values for eDirectory Objects

At a more granular layer, you can see in this article, about different move events:
Open Call for IDM Move Event Documents

Each driver sends a move again, in subtly different ways, based on what is happening in the connected system.

Then we run into error codes, where each driver has its own unique set of error codes. I have been working on a series of articles on this topic:

For the Active Directory driver I have these written so far:

• Active Directory Driver Error Messages - Part 1

• Active Directory Driver Error Messages - Part 2

• Active Directory Driver Error Messages - Part 3

• Active Directory Driver Error Messages - Part 4

and I have part five under construction at the moment.

For the JDBC driver, there are these written:

• Error Codes of the Novell Identity Manager Driver for JDBC: Part 1 of 4

• Error Codes of the Novell Identity Manager Driver for JDBC: Part 2 of 4

• Error Codes of the Novell Identity Manager Driver for JDBC: Part 3 of 4

• Error Codes of the Novell Identity Manager Driver for JDBC: Part 4 of 4

If I can find the time, I have a set of errors for the GroupWise driver, the SAP HR driver, and the eDirectory driver that I need to shape into articles.

As you can imagine, there are so many possible errors, and while some are really easy and obvious (my favorite kind! Where the error code is really instructive, and really does tell you what the problem is, in clear english in the error message. If your native language is NOT english, sorry, but what can I do? Most of the code is written in english!) others are really odd, and seem to make no sense.

Often I find that getting a second set of eyes to look at it, can catch the subtle typo, or mistake, quite quickly whereas you might have spent hours looking at it. It becomes very annoying when you have spent hours looking at it, but someone who looks at it for a moment, sees the issue right away. This is one of those unable to see the forest for the trees type of issues, and you should not take it personally. It happens to all of us! This is also one of those places where working as a team, can be much more effective than working by yourself.

If you do not have a team, you can join a virtual team, and consider posting about it in the Novell Support Forums, which are hosted at http://forums.novell.com (if you can live with a web based vBulletin interface. I happen to be a big fan of NNTP protocol, so I use a news reader like Thunderbird, to connect to nntp://forums.novell.com which I find works better.) and look for the forum: novell.support.identity-manager.engine-drivers

If you are having an interesting problem, consider posting a sample from DSTrace, and discussing your issue.

If you are not familiar with getting and reading dstrace, then you must read this article, by Fernando Frietas, who works at Novell Technical Support, who has written one of the best articles on the topic that I have yet to see!
Capturing and Reading Novell Identity Manager Traces

I would also suggest you think about the problem, and spend some time getting the question nicely written up, since I often find the process of getting the question assembled helps me consider new avenues to troubleshoot, and often helps me find the real answer. At which point I have this lovely question all written up with examples of what breaks, what works, and what I think happened, so I do what I am doing now, and submit it as a Cool Solution article. However, when it does not get me close enough to resolve the question, posting it to the support forums, and then getting a whole new set of eyes on the problem, can be very effective to getting a solution.

My boss recently ran into this inexplicable error, and I looked at it at the time, and we both threw our hands up in the air and decided, we will pretty much have to live with it, since it was mostly harmless (The Hitchhikers Guide to the Galaxy's description of planet Earth).

Recently I revisited the problem, and was in a more stubborn mind set and was able to track it down. This was one of those inexplicable errors, where once you figure it out, you end up saying, seriously? (There is a terrible Saturday Night Live skit with Amy Poehler, where she and her co host talk about the weeks news, and to each ridiculous item, they both respond with "Seriously?" and I feel that way about this one!)

Our system is running eDirectory 8.8.5 with FTF1, on SLES 10 SP2, with Identity Manager 3.6.1 with the engine patch, and the GroupWise driver ir2a patch.

We have an Active Directory driver, querying eDirectory, for DirXML-ADContext, based on distinguished name (DN) values coming out of Active Directory on a group objects member list. So we know we have real DN values coming from Active Directory, and we know they all ought to be associated, and thus resolvable in eDirectory. However to PROVE to ourselves that they are resolvable, we wanted to query eDirectory to find a user object that has the DN value in the DirXML-ADContext attribute. This is happening on the Publisher channel, therefore the query docs are for the destination data store, eDirectory.

However, we see the queries go to eDirectory and return with a -613 SYNTAX VIOLATION. Or more specifically:

Code(-9010) An exception occurred: novell.jclient.JCException: initVlistIterator -613 ERR_SYNTAX_VIOLATION

Here is a trace of the event, and the resulting failure.

[10/29/09 08:12:08.873]:AMERICAS-AD PT:          Action: do-set-local-variable("MEMBER-OBJECT",scope="policy",arg-node-set(token-query(class-name="User",arg-dn("acme"),arg-match-attr("DirXML-ADContext",token-local-variable("current-node"))))).
[10/29/09 08:12:08.875]:AMERICAS-AD PT:            arg-node-set(token-query(class-name="User",arg-dn("acme"),arg-match-attr("DirXML-ADContext",token-local-variable("current-node"))))
[10/29/09 08:12:08.876]:AMERICAS-AD PT:              token-query(class-name="User",arg-dn("acme"),arg-match-attr("DirXML-ADContext",token-local-variable("current-node")))
[10/29/09 08:12:08.877]:AMERICAS-AD PT:                arg-dn("acme")
[10/29/09 08:12:08.877]:AMERICAS-AD PT:                  token-text("acme")
[10/29/09 08:12:08.878]:AMERICAS-AD PT:                  Arg Value: "acme".
[10/29/09 08:12:08.878]:AMERICAS-AD PT:                arg-match-attr("DirXML-ADContext",token-local-variable("current-node"))
[10/29/09 08:12:08.879]:AMERICAS-AD PT:                  arg-string(token-local-variable("current-node"))
[10/29/09 08:12:08.879]:AMERICAS-AD PT:                    token-local-variable("current-node")
[10/29/09 08:12:08.880]:AMERICAS-AD PT:                      Token Value: "CN=Jones\, Smith,OU=Migrated,DC=americas,DC=acme,DC=corp".
[10/29/09 08:12:08.881]:AMERICAS-AD PT:                    Arg Value: "CN=Jones\, Smith,OU=Migrated,DC=americas,DC=acme,DC=corp".
[10/29/09 08:12:08.882]:AMERICAS-AD PT:                Query from policy
[10/29/09 08:12:08.882]:AMERICAS-AD PT:                
<nds dtdversion="3.5" ndsversion="8.x">
  <source>
    <product version="3.6.1.4427">DirXML</product>
    <contact>Novell, Inc.</contact>
  </source>
  <input>
    <query class-name="User" dest-dn="acme" scope="subtree">
      <search-class class-name="User"/>
      <search-attr attr-name="DirXML-ADContext">
        <value type="string">CN=Jones\, Smith,OU=Migrated,DC=americas,DC=acme,DC=corp</value>
      </search-attr>
      <read-attr/>
    </query>
  </input>
</nds>
[10/29/09 08:12:08.885]:AMERICAS-AD PT:                Pumping XDS to eDirectory.
[10/29/09 08:12:08.886]:AMERICAS-AD PT:                Performing operation query for acme.
[10/29/09 08:12:08.891]:AMERICAS-AD PT:                Query from policy result
[10/29/09 08:12:08.892]:AMERICAS-AD PT:                
<nds dtdversion="3.5" ndsversion="8.x">
  <source>
    <product version="3.6.1.4427">DirXML</product>
    <contact>Novell, Inc.</contact>
  </source>
  <output>
    <status event-id="0" level="error">Code(-9010) An exception occurred: novell.jclient.JCException: initVlistIterator -613 ERR_SYNTAX_VIOLATION</status>
  </output>
</nds>

I noticed that there was a backslash in the DN, which makes sense, as there is a comma in it as well that needs to be escaped, so the DN of CN=Jones\, Smith,OU=Migrated,DC=americas,DC=acme,DC=corp looks to be good and appropriate. The comma is escaped properly.

Thus we know that the DN is properly escape, for commas, with a \, (backslash comma) and that is the correct value stored in DirXML-ADContext.when I checked for that specific user.

An LDAP query for user finds them. Actually, I was lazy and did a query for (DirXML-ADContext=cn=Jones*) and that works. But (DirXML-ADContext=CN=Jones\, Smith,OU=Migrated,DC=americas,DC=acme,DC=corp) fails. So that was my first clue.

I thought maybe I needed to quote enclose this, since there are spaces and equal signs, and what not, but when I did that (DirXML-ADContext="CN=Jones\, Smith,OU=Migrated,DC=americas,DC=acme,DC=corp") it too failed to return a value.

At first we thought it might be a period in the string, but it fails for users without periods as well with a 613. But interestingly, on a user name without a comma, and thus without a backslash comma in the string, it does seem to work.

Here is a sample trace that DID work, so you can see what it SHOULD be returning, instead of the -613 error.

[10/29/09 08:12:09.334]:AMERICAS-AD PT:          Action: do-set-local-variable("MEMBER-OBJECT",scope="policy",arg-node-set(token-query(class-name="User",arg-dn("acme"),arg-match-attr("DirXML-ADContext",token-local-variable("current-node"))))).
[10/29/09 08:12:09.336]:AMERICAS-AD PT:            arg-node-set(token-query(class-name="User",arg-dn("acme"),arg-match-attr("DirXML-ADContext",token-local-variable("current-node"))))
[10/29/09 08:12:09.337]:AMERICAS-AD PT:              token-query(class-name="User",arg-dn("acme"),arg-match-attr("DirXML-ADContext",token-local-variable("current-node")))
[10/29/09 08:12:09.338]:AMERICAS-AD PT:                arg-dn("acme")
[10/29/09 08:12:09.339]:AMERICAS-AD PT:                  token-text("acme")
[10/29/09 08:12:09.339]:AMERICAS-AD PT:                  Arg Value: "acme".
[10/29/09 08:12:09.340]:AMERICAS-AD PT:                arg-match-attr("DirXML-ADContext",token-local-variable("current-node"))
[10/29/09 08:12:09.340]:AMERICAS-AD PT:                  arg-string(token-local-variable("current-node"))
[10/29/09 08:12:09.341]:AMERICAS-AD PT:                    token-local-variable("current-node")
[10/29/09 08:12:09.342]:AMERICAS-AD PT:                      Token Value: "CN=mpr admin,OU=Migrated,DC=americas,DC=acme,DC=corp".
[10/29/09 08:12:09.342]:AMERICAS-AD PT:                    Arg Value: "CN=mpr admin,OU=Migrated,DC=americas,DC=acme,DC=corp".
[10/29/09 08:12:09.343]:AMERICAS-AD PT:                Query from policy
[10/29/09 08:12:09.344]:AMERICAS-AD PT:                
<nds dtdversion="3.5" ndsversion="8.x">
  <source>
    <product version="3.6.1.4427">DirXML</product>
    <contact>Novell, Inc.</contact>
  </source>
  <input>
    <query class-name="User" dest-dn="acme" scope="subtree">
      <search-class class-name="User"/>
      <search-attr attr-name="DirXML-ADContext">
        <value type="string">CN=mpr admin,OU=Migrated,DC=americas,DC=acme,DC=corp</value>
      </search-attr>
      <read-attr/>
    </query>
  </input>
</nds>
[10/29/09 08:12:09.347]:AMERICAS-AD PT:                Pumping XDS to eDirectory.
[10/29/09 08:12:09.347]:AMERICAS-AD PT:                Performing operation query for acme.
[10/29/09 08:12:09.349]:AMERICAS-AD PT:                Query from policy result
[10/29/09 08:12:09.350]:AMERICAS-AD PT:                
<nds dtdversion="3.5" ndsversion="8.x">
  <source>
    <product version="3.6.1.4427">DirXML</product>
    <contact>Novell, Inc.</contact>
  </source>
  <output>
    <instance class-name="User" event-id="0" qualified-src-dn="O=acme\OU=Users\CN=mpradmin" src-dn="\acme-IDV\acme\Users\mpradmin" src-entry-id="35596">
      <association state="associated">43e82d144dc67d4e9afc1c682a52a69d</association>
    </instance>
    <status event-id="0" level="success"></status>
  </output>
</nds>

Very odd. So I suspected this is a Case Ignore string (single valued DirXML-ADContext attr) syntax matching error problem.

Schema reference does not define clearly how matching works on backslash characters... It ought to be ok, I mean, it is just a character. It is escaping the comma. Do I have to escape the escaping to try:

(DirXML-ADContext="CN=Jones\\, Smith,OU=Migrated,DC=americas,DC=acme,DC=corp")

Well that works in an LDAP query. I went and updated to see if that helps in Identity Manager, and lo and behold, that works without an error. Now testing in LDAP is effective, since the schema definition in eDirectory defines how the compare method for each attribute is used. There are equality and sub string compares available, depending on the attribute and the schema syntax type. The NLDAP LDAP server that is part of eDirectory has to honour eDirectory underneath it, when it provides a response to an LDAP client. (On Netware it is NLDAP.NLM and you can load and unload it by hand. On Windows eDirectory servers, it is nldap,dlm you can load and unload it from the Dhost.exe interface. On Unix and Linux you can use ndstrace, and execute the command "modules" to see that which is loaded and running, and then "unload nldap" or "load nldap" to reload it.)

It looks like you need to escape the escaped character.

In order to fix this in my code, where I was iterating through the member list coming from Active Directory and searching for the local variable current-node, I had to do a replace all.

Here is where it gets funny. So with a replace-all token in Argument Builder, what do you think you need to specify to replace a single backslash with two backslashes?

Well in the case of the replace-all token, it implicitly uses regular expressions to do the matching. That means you need to escape the backslash.

This ends up with replace all \\ with \\\\ and yes, that is two backslashes with four backslashes.

You have to escape the escape character that you are replacing, (and then replace it with an escape character escaped, and then do it a second time) in an attempt to escape and already escaped escape character. (Hmm, there is an elegance to that comment I suppose).

It appears that when querying into eDirectory even for a string attribute (which was the big surprise) that contains a backslash character, you need to escape it with another backslash.

We ran into this in the JDBC driver, where we had to escape single and double quotes, when building a SQL statement directly (like in this article:
Using the JDBC Driver and Direct SQL

But this one really did surprise me, when it comes to a simple string. You should keep this in mind when looking at any string attribute that is storing a DN, because most DN's that contain funny characters (spaces, commas, backslash, etc) you ought to watch out for this kind of error.

Add this one to the list of strange things you have to keep in mind when working in Identity Manager. No doubt someone could find the one line reference buried deep in the documentation that explains this. But I did not find it, nor had I run into this before, even after years of working with Novell Identity Manager. That is some of the fun of working in this kind of product, since there is always something new to learn. Might get more and more subtle but still things to learn.

If you have run across something as esoteric as this example, please consider writing it up and submitting it to Cool Solutions, so that when someone else does a Google search for some of the error string, they might find your document, and save themselves some time in resolving it.