-613 ERR_SYNTAX_VIOLATION Common Causes & Solutions

Odds are if you have worked with drivers in the Novell/NetIQ Identity Management (IDM) product you have see the following error at least once:

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

This error can cause untold amounts of frustration for developers and support technicians who attempt to determine the cause of the error.  While the error does a great job of telling you why a transaction did not succeed, a syntax violation error as indicated in the message, it does not do a very good job of describing what syntax violation was encountered.  In fact, there are at least three (3) typical scenarios that can generate this error message.  This means that while you know there was a violation in the transaction that there could be multiple reasons why and that it is up to you (or someone else qualified to evaluate IDM data) to determine which scenario, or scenarios, existed within that transaction that led to the failure.  Of course, understanding the scenario does not provide a fix but it does allow the developer(s) to focus on the specific policies within the driver that govern that scenario.

So what are the three most common scenarios that will result in the dreaded -613 ERR_SYNTAX_VIOLATION?

1. A missing required attribute in an Add event transaction
2. An event transaction that attempts to add multiple attribute values to a single-valued attribute
3. An event transaction that attempts to add a value that does not match the target attribute's format

Let's take a few minutes to look at each scenario to learn a little bit about how those scenarios come to be and how to resolve them.

Scenario 1: A Missing Required Attribute In An Add Event Transaction

Just like the scenario title suggests when creating an object/record the Input doc for the Add event is missing some data that is required by the destination application/system.  Now, obviously this means that there can often be a variety of things that could go wrong here and that is true.  Different systems may require different values for creation to occur.  This means that it is always important as a developer to know what values are required by the target system and then add the necessary policies that enforce those requirements.  In most drivers there always exists a policy with a set of rules that check for those required attributes and in the event a required attribute is missing the Add event is vetoed.  This allows the driver to prevent an object creation until all of the necessary data exists or can be generated via preceding policies thus preventing the aforementioned error.

Now this standard required attribute check will catch most situations that lead to this error but is not the only cause of the -613 error in an Add event.  Another cause of this error is often times related to the dest-dn value that is generally created in a driver's Placement policy.  If that Placement policy is missing or malformed so that it doesn't execute you will be left without a dest-dn value.  Obviously a dest-dn value is required because that value tells the driver where to create the new record/object in the target system.  So, if you have an Add event transaction with no dest-dn value the driver will not be able to create the object in the proper destination and will ultimately send a malformed add command to the target system that will fail.

Scenario 2: An Event Transaction Attempts To Add Multiple Values To A Single-Valued Attribute

Again, the scenario title tells you what you need to know at a high level but doesn't exactly give any details on common causes that lead to that scenario and there are two (2) main causes that creates this scenario in an IDM driver.

The first scenario is pretty simple and straightforward; the source system allows for (and contains) multiple values for a particular attribute but the destination system only allows one value for that attribute.  For example, let's say we are synchronizing data from eDirectory to another LDAP source.  In eDirectory we are allowed to have multiple values in the Telephone Number attribute but in the target LDAP directory there is only one value allowed for Telephone Number.  What this means is that when that record is synchronized to the external LDAP directory that the driver will try to insert both values into a single attribute with a command that looks like the following example:

<modify-attr attr-name="Telephone Number">
        <remove-all-values/>
        <add-value>
          <value type="string">555-555-1111</value>
        </add-value>
        <add-value>
          <value type="string">555-555-2222</value>
        </add-value>
</modify-attr>

This means that the driver will basically try to input to values into a single attribute that will fail because the attribute only accepts ones value but the driver is providing two.  In the event that this is the case you are faced with the common solution is to only synch one value from the source to the destination and ignore the other values.  This can be controversial though since there is no method to determine which value in eDirectory would be a primary number or a number for a particular location or device, i.e. home number, office number, cell number, etc., so it is possible that the value synchronized would not be the preferred number.  A solid understanding of the source data and the destination schema is critical for preventing or solving issues when this situation occurs.  Once everyone understands what they have in terms of source data and what they need in terms of destination data a solution can be developed but there is no one single answer to this situation.

A for more common cause of this scenario though is when data in the Input doc needs to be "transformed" and in that transformation a duplicate add/modify attribute command is added to the Input doc by accident, as shown in the following example:

<modify-attr attr-name="Telephone Number"> 
        <remove-all-values/> 
        <add-value> 
          <value type="string">555-555-1111</value> 
        </add-value> 
<modify-attr attr-name="Telephone Number">  
        <add-value> 
          <value type="string">(555) 555-1111</value> 
        </add-value> 
</modify-attr>

In many cases there will be a policy that performs some type of formatting of a target value to meet some requirement of the destination application/system.  Typically, these policies perform four (4) actions:

1. Store the current value in a local variable
2. Strip the current operation attribute from the Input doc
3. Format the local variable value to the desired format
4. Add the reformatted value back to the Input doc

However, it is common that the policies will not have Step #2 which is critical.  By omitting that step the original value remains in the Input doc and when Step #4 is performed you end up with an Input doc that calls for two values to added to a single attribute (Telephone Number in our example).  Just like before, if the target application/system does not accept two values for that attribute the transaction will fail with a -613 error.

The solution to this situation is obvious.  If you find multiple references to an attribute in your Input doc review the driver policies and log files to determine which policy(ies) are creating the duplication and address them accordingly.  Again, the common culprit here is that some transformation is done on the data but the original, unwanted value is not properly removed from the transaction.

Scenario 3: An Event Transaction Attempts To Add A Value That Does Not Match The Target Attribute's Format

Just like before the scenario title should give you a pretty good idea of what has gone wrong but we will take a closer look it.

For this situation let's say that you have a driver policy that needs to add a user to a target eDirectory group based on some attribute value that denotes that user's position within your organization.  In that situation you would expect to have a policy that compares the attribute value denoting position and then based on that evaluation an action that adds the destination attribute (Group Membership) value equal to the proper group.  Sounds simple, right?

Well, unlike most attributes the Group Membership attribute is a DN formatted attribute.  This means that if you just say "add destination attribute Group Membership value equal to <Group Name>" the transaction will fail.  <Group Name> is not a valid DN syntax even if it is the proper group name.

The same is true if you try to add a string value of "Gary" to a boolean formatted attribute or a string value of "IDM" to an integer formatted attribute.  Those values do not match the syntax of the target attribute and can result in the -613 error.

This situation can actually be the more difficult of the three scenarios listed here to troubleshoot.  The transaction event data in the log file will specify the value's format (<value type="string">555-555-1111</value>) but this may not always match the format in the schema that defines that attribute.  And just like with most things there are multiple ways that this mismatch can be created.

1. If a driver's policy is responsible for setting/adding an attribute value to a target attribute the policy actually specifies the value format (which defaults to string) so it is likely that the policy specifies the incorrect format.  In this case when you look at the driver log file the value will match the format declared in the policy so on the face of it everything will look fine.  As stated previously in this article a full understanding of the data is critical.  If you know an attribute has a boolean syntax and you see a string value specified in the transaction event then you can determine that is the cause of your problem.  Generally this type of mismatch is caused by a policy that specifies the wrong format for the value being set and a simple update of the policy to the correct format will resolve the issue.
2. Two attributes are mapped to one another in the driver's schema mapping that have different syntaxes and the driver attempts to do a direct synchronization of the data with no transformation or conversion from one data type to the other.  This means that if you have a string attribute mapped to an integer attribute any attempt to synch data between those attributes without transforming the value to the appropriate format first will result in the -613.  

And finally, there is one more situation that cause this scenario and it is one that most people would not expect; adding a null or blank value to an eDirectory attribute.  Now this situation may also be true for other external systems but is common when synchronizing data from a database to eDirectory.

Consider this, when reading data from a database using a JDBC driver the driver reads all fields in that table regardless of whether or not the field actually contains real data.  This means that the driver will pull empty fields from the table and attempt to populate eDirectory with blank values, which is not allowed in eDirectory.  Take a look at the examples below:

<add-attr attr-name="Initials">
    <value type="string"></value>
</add-attr>

or

<modify-attr attr-name="Telephone Number">  
       <add-value> 
          <value type="string"></value> 
       </add-value> 
</modify-attr>

If you see something like that in your Input doc then you know that is part of your problem.  eDirectory will not allow you to populate an attribute with a null or blank value because let's face it, that isn't a real value so you are pretty much telling eDirectory to populate a value with nothing and that violates eDirectory's syntax for pretty much all of its attributes.

Side Note: eDirectory does not like populating attributes with a blank space either (<value type="string"> </value>).  eDirectory will treat that as a null value as the engine will automatically "trim" the value and this will result in the same -613 error.

This situation is generally caused by a database table that contains optional fields like Middle Name, Initials, Suffix, etc. so it creates a scenario where the driver reads fields that do not have an actual value but the driver is configured to synch those fields to eDirectory.  The easiest way to prevent this issue from occurring is to determine what fields are optional in the database and then create policies in the driver that tests those fields/attribute values for a length of 1 or greater and if the value is blank or null (essentially length less than 1) strip that attribute from the operation data/Input doc.

Example: (if XPath expression true "string-length(<attribute or variable name>) > 0")

So there you have it, the most common causes for the vague -613 ERR_SYNTAX_VIOLATION error in eDirectory drivers!  The best way to avoid getting into trouble with this error is to understand the data on both sides of the driver and how the driver/engine treats your data.  Also, keep in mind that if you are dealing with several attributes that in many cases if one attribute has a problem that there may be others with the same issue so look at all attributes, all values and consider all scenarios when looking through your driver logs to minimize the amount of back and forth required to get success.  Pretty much every time I have seen the -613 error there has been at least two attributes or values that were messed up or missing.

Questions, comments or concerns? Feel free to reach out to us below, or email us at IDMWORKS to learn more about how you can protect your organization and customers.