A Methodology for Troubleshooting DirXML
Articles and Tips: article
Net Solutions Support
Novell, Inc.
iforst@novell.com
Hicham Mourad
Net Solutions Support
Novell, Inc.
hmourad@novell.com
Garth Williamson
Net Solutions Support
Novell, Inc.
gwilliamson@novell.com
01 Sep 2002
DirXML implementations can be complex, due to the interaction between multiple drivers and the customization that can be made to the different types of event handling withing DirXML. Troubleshooting problems in such a system can be difficult without the proper tools and a methodical approach. This AppNote describes the tools that are commonly used to troubleshoot DirXML issues and outlines a recommended methodology for identifying and resolving problems.
This AppNote is based on a presentation given at BrainShare 2002 by the Worldwide Net Solutions Support team.
- Introduction
- DirXML Troubleshooting Tools
- DirXML Troubleshooting Methodology
- DirXML Troubleshooting Example
- Conclusion
|
Topics |
DirXML, troubleshooting, directory-enabled applications |
|
Products |
DirXML 1.x |
|
Audience |
application developers |
|
Level |
intermediate |
|
Prerequisite Skills |
familiarity with architecture and use of DirXML |
|
Operating System |
n/a |
|
Tools |
DSTRACE, iMonitor, Java Trace File, NXSL Processor |
|
Sample Code |
no |
Introduction
One of the many strengths of Novell's DirXML is the flexibility that it provides in manipulating events. However, this flexibility can also introduce a certain measure of complexity due to the customization that can be made to the different types of event handling within DirXML. Another level of complexity is added when more than one driver exists within your solution. It is this complexity that can make DirXML troubleshooting difficult for those who are not armed with the proper tools and an understanding of how best to approach a given problem in a methodical manner.
This AppNote introduces a recommended methodology for troubleshooting DirXML issues. This methodology has been developed by a group of Novell Worldwide Net Solution support engineers, based on their experiences with many different DirXML implementations of varying sizes. The information in this AppNote should assist you in getting enough of an understanding of a system to be able to easily diagnose and resolve an issue.
In presenting this material, the authors assume the reader has an intermediate understanding of DirXML and has used the product. Since there are many different DirXML drivers and many developers who are writing custom drivers, driver-specific issues are not discussed in this AppNote.
DirXML Troubleshooting Tools
When troubleshooting DirXML related issues, it is important to be able to capture trace files that will assist you in determining where the problem may lie. This section discusses the different tools that you can use to capture the appropriate trace files. It also discusses the NXSL Processor and how it can be used to troubleshoot some DirXML issues.
Trace Types and Levels
In order to capture the right data while troubleshooting a DirXML issue, it is important to understand the different types of traces and their levels.
Note: Gathering traces can be CPU intensive and therefore can cause performance issues. In addition, because trace files can get very large in size, you should exercise caution when capturing them to your server. You need to bee sure you have enough disk space so that you don't run out when capturing trace files. For these reasons, it is recommended that you capture trace files only when troubleshooting issues, and not on a regular basis.
DirXML-DriverTraceLevel. DirXML-DriverTraceLevel is used to capture driver-related information. This is useful when troubleshooting DirXML driver-related issues. The driver trace level can be set at different levels; the most common is 3. The levels are described in the following table.
|
Value
|
Description
|
|
0 |
No trace messages are displayed or logged |
|
1 |
Basic trace messages are displayed and logged |
|
2 |
Level 1 messages, plus the contents of XML documents used during event processing, are displayed and logged |
|
3 |
Level 2 messages, plus extensive rule processing messages, are displayed and logged |
DirXML-XSLTraceLevel. DirXML-XSLTraceLevel is used to capture information relating to XSLT (Extensible Stylesheet Language Transformations). This type of trace is mainly used by developers when troubleshooting issues relating to stylesheet code. The XSLT trace level can be set at different levels; the most common is 3 or 4. The levels are described in the following table.
|
Value
|
Description
|
|
0 |
No trace messages are displayed or logged |
|
1 |
Trace source node processing, output to standard error |
|
2 |
Trace rule instantiations, in addition to all of the above |
|
3 |
Trace template instantiations, in addition to all of the above |
|
4 |
Trace rule matching and select expression details, in addition to all of the above |
Enabling DirXML-Related Trace Levels
Trace levels are set on the DirXML DRIVER-SET object; therefore the traces generated are not driver specific, but DRIVER-SET specific. This means if you have multiple drivers configured as part of your DRIVER-SET, your trace will include information from all drivers that are in a running state.
To enable trace levels, follow these steps:
In ConsoleOne, right-click on the DirXML DRIVER-SET object.
Select Properties.
Select the Other tab.
Click on Add, and then from the list select "DirXML-DriverTraceLevel" and enter a trace level value from 0 to 3 in the text box.
If you are troubleshooting XSLT-related issues, also add from the list "DirXML-XSLTraceLevel" and enter a value from 0 to 4 in the text box.
Figure 1 shows an example of the DirXML Driver and XSL trace level settings.
Figure 1: DirXML Driver and XSL Trace Level settings.
The DSTRACE Utility
The DSTRACE utility is easy to use-many administrators and engineers have used it to perform eDirectory health checks. It can be run on any platform supported by eDirectory: NetWare, Windows NT/2000, and UNIX/Linux. Keep in mind that running this utility can cause performance issues and therefore it should be used only for troubleshooting purposes.
Running DSTRACE on NetWare. Here's how to use DSTRACE on NetWare.
Type the following commands at the server console prompt:
LOAD DSTRACE
DSTRACE -ALL
DSTRACE +DVRS shows everything that is part of the DirXML module, including driver and XSL information
DSTRACE +DXML shows caching of events and anything related to the TAO (driver cache) file
DSTRACE FILE ON to log the trace to sys:system\dstrace.log
DSTRACE SCREEN ON to display live trace on the server console screen
Figure 2 shows the DSTRACE Configuration as seen on the console screen.
Figure 2: The DSTRACE Configuration screen.
Running DSTRACE on Windows NT/2000. Here's how to use DSTRACE on Windows NT/2000.
Start DSTRACE.DLM from the eDirectory Services Console (NDSCONS.EXE), as shown in Figure 3.
Figure 3: Starting the DSTRACE utility from the NDS Services Console.
From the Edit menu, select Options to bring up the NDS Trace Options screen shown in Figure 4.
Figure 4: The NDS Trace Options screen.
Click the Clear All button to deselect all events. Then select (check) the following options:
DirXML to show caching of events and anything related to the TAO (driver cache) file
DirXML Drivers to show everything that is part of the DirXML module, including driver and XSL information
To log the trace to a file, select the File menu, select New, and then enter the path and file name.
Running DSTRACE on UNIX/Linux. Here's how to use DSTRACE on the UNIX/Linux platform.
Type the following commands at the server console prompt:
ndstrace
set dstrace = nodebug turns off any trace filters
set dstrace = +drvs shows everything that is part of the DirXML module, including driver and XSL information
set dstrace = +dxml shows caching of events and anything related to the TAO (driver cache) file
dstrace file on to log the trace to /var/nds/ndstrace.log
Figure 5 shows the NDSTrace configuration as displayed on the server console screen.
Figure 5: The NDSTrace Configuration screen.
The iMonitor Utility
Novell's iMonitor utility provides cross-platform monitoring and diagnostic capability to all servers in your eDirectory tree. This utility lets you monitor your servers from any location on your network where a Web browser is available. It is easy to use and displays real-time trace information. Another of its key features includes being able to capture trace files remotely through a Web browser.
Note: Versions of iMonitor prior to v1.5 caused some large XML documents to be truncated. If you have a prior version, upgrade to the latest release available at http://download.novell.com.
To start iMonitor, use a Web browser to go to the appropriate default URL for your platform:
NetWare running eDirectory 8.5 or higher: http://server.company.com:/nds
Windows NT/2000 running eDirectory 8.5 or higher: http://server.company.com/nds
UNIX/Linux running eDirectory 8.5 or higher: http://server.company.com/nds
You can substitute the IP address of the server in place of the "server.company.com" DNS name in the default URLs shown above.
These URLs are valid provided there is no Web Server running on the server. If you have a Web Server running on any of the above platforms, the URL becomes http://server.company.com:8008/nds or http://ip-address-of-server:8008/nds.
Figure 6 shows the DS Trace Options screen in iMonitor.
Figure 6: The Trace Configuration screen in iMonitor.
For more detailed information on iMonitor, refer to the online documentation available at http://www.novell.com/documentation.
Java Trace File
Since DirXML uses Java, you can use the Java Trace File option to capture trace information to a file. However, only the pieces of DirXML that utilize Java will be captured to the trace file. It won't include information about the drivers cache file, or driver starting and stopping information. If you are troubleshooting a driver startup/shutdown problem, this wouldn't be the ideal tool to use for capturing the trace; you should use one of the other available tools. Another limitation of the Java Trace File tool is that it doesn't show real-time information; it just logs information to a file.
Note: This option has no auto-roll mechanism, nor can you set a maximum file size. Therefore it is important to have adequate disk space when using this option, or you run the risk of having the trace file consume all of your disk space.
As with the other tools described herein, you will experience a performance hit when using the Java Trace File, so you should only use it when troubleshooting.
Enabling the Java Trace File. Trace levels are set on the DRIVER-SET object. Therefore the traces generated are not driver specific, but DRIVER-SET specific. This means if you have multiple drivers configured as part of your DRIVER-SET, your trace will include trace information from all drivers in a running state.
To enable Java Trace levels, follow these steps:
In ConsoleOne, right-click on a DirXML DRIVER-SET object.
Select Properties.
Select the Other tab.
Click Add and from the list select the "DirXML-JavaTraceFile" attribute.
Enter the appropriate path in the text box below DirXML-JavaTraceFile:
NetWare - volume:/path/filename (i.e., SYS:TEMP\JAVATRACE.TXT)
Windows NT/2000 - drive:\path\filename (i.e., C:\temp\JAVA- TRACE.TXT)
UNIX/Linux - /path/path/filename (i.e., /var/nds/JAVATRACE.TXT)
Figure 7 shows the Java trace file path entered for a Windows NT/2000 environment.
Figure 7: Specifying the path for the Java Trace File.
The NXSL Processor
The NXSL (Novell XSL) Processor is an XSL processor that is built into the DirXML engine. It is provided as a standalone utility, which gives you the flexibility to test XML/XSLT documents in standalone mode. This is a great benefit when troubleshooting, since you don't have to test in your production environment.
You can use the NXSL Processor for the following troubleshooting tasks:
Validating XSLT syntax and logic
Checking for well-formed XML and XSLT documents
Testing XSLT code with different event types, without impact to your production environment
Due to the fact that the NXSL Processor is a standalone troubleshooting utility, there are some situations in which you will not want to (and cannot) use it:
Testing XSLT stylesheets that have queries in them. For queries to work, you need to be able to communicate with the application and with eDirectory. Due to the standalone nature of the NXSL Processor, this can't be done.
Testing XSLT stylesheet and rule(s) interaction. This again is due to the fact that the NXSL Processor is being used in standalone mode and you can't access the DirXML drivers' rules.
End-to-end testing (for obvious reasons).
Checking for well-formed XDS documents. (XDS documents are XML documents that are written to syntactically conform to the NDS Document Definition Type known as the NDS DTD.)
Configuring the NXSL Processor. To configure the NXSL Processor, do the following:
On a Windows NT/2000 workstation, install the Java Runtime Environment 1.3.1 or higher. (This can be downloaded from the Sun Microsystems Web site at http://www.sun.com/download/.)
From the DirXML CD, copy the following files to C:\NOVELL\XSL:
RT.JARNXSL.JARCOLLECTIONS.JARXP.JAR
Copy the following text to a batch file (C:\NOVELL\XSL\NXSL.BAT):
@echo offsetlocalrem set JAVA_HOME to your JRE or JDK directorySET JAVA_HOME=C:\jdk1.3.1_01\jreSET NXSL_JARS=C:\novell\xslrem set NXSL_JARS to the location containing nxsl.jar, xp.jar, and collections.jarset CLASSPATH=%JAVA_HOME%\lib\rt.jarset CLASSPATH=%CLASSPATH%;%NXSL_JARS%\nxsl.jar;%NXSL_JARS%\collections.jarset CLASSPATH=%CLASSPATH%;%NXSL_JARS%\xp.jarset nxsl=%JAVA_HOME%\bin\java -classpath %CLASSPATH% com.novell.xsl.nxsl%nxsl% -e1 %1 %2 %3 %4 %5 %6 %7 %8endlocal
Using the NXSL Processor. Once you have configured the NXSL Processor, you can run it by typing the NXSL command (with options) at the DOS prompt. Here are some examples of common NXSL commands to process source XML documents with an XSLT stylesheet.
NXSL SOURCE.XML STYLESHEET.XSL
This command will process the SOURCE.XML document with the stylesheet called STYLESHEET.XSL. The results will be output to screen.
NXSL -O RESULT.XML SOURCE.XML STYLESHEET.XSL
This command will process the SOURCE.XML document with the STYLESHEET.XSL stylesheet, with the results output to the RESULT.XML file.
NXSL -D[1-4] SOURCE.XML STYLESHEET.XSL
When used in addition to the first example above, this command will generate detailed trace messages according to the trace level set via the -D option (see "Enabling DirXML-Related Trace Levels" above for more information).
NXSL
This command will display the help screen shown in Figure 8. This is also a quick way to verify that the NXSL Processor is configured correctly.
Figure 8: The help screen for the NXSL command.
DirXML Troubleshooting Methodology
This section presents a recommended methodology to follow to troubleshoot DirXML. If at any time in the troubleshooting process you have a strong feeling about what may be the cause of the issue, follow your hunch. However, if it turns out that your hunch wasn't right, it is best to return to the recommended procedure rather than deviate or try to take shortcuts.
Note: Some of these steps may not apply to you if you have a detailed understanding of the environment and are very familiar with the DirXML implementation you are troubleshooting.
Figure 9 is a flow chart of the DirXML troubleshooting methodology.
Figure 9: DirXML troubleshooting methodology flow chart.
Identify the General Issue
During this initial stage, you need to understand what the general problem may be. You can then attempt to isolate it to one of the following categories:
The driver isn't starting.
The driver is stopping unexpectedly.
The driver is stopping after it has been running successfully for a specific period of time.
The rules/stylesheets are not functioning as expected.
The rules/stylesheets are generating unexpected output results.
You experiencing unexpected eDirectory errors.
It is important at this stage to attempt to further identify the specific action that is causing the issue. Possibilities include the following:
Starting or stopping the driver
Creating a user, deleting a user, moving a user, or renaming a user
Understand the DirXML Environment
During this stage you need to learn more about the DirXML environment by doing the following:
Identify the platform that eDirectory and DirXML are running on. Document and be aware of the different product versions in use.
Identify the different DirXML drivers that are in use.
Understand the basic data flow of data between the different applications involved and the Publisher and Subscriber channels.
Identify outstanding eDirectory issues (if applicable). Since eDirectory is the underlying technology on which DirXML solutions are implemented, it is important that eDirectory be healthy and error-free.
Understand eDirectory replica placement. It is important that replicas be carefully placed. DirXML drivers require real copies of objects being manipulated or modified in order for them to perform their functions.
Obtain a list of Driver Exports. Driver Exports can be extremely helpful when troubleshooting, as they provide a snapshot of the driver configuration including rules, stylesheets, and filters. They can also be imported into a test tree for review.
Understand the General Driver Functionality
This stage involves arriving at a better understanding of the customizations that have been made to the DirXML drivers involved.
Review the driver exports that you have imported into a test environment during the previous stage. It is also helpful to review the driver documentation.
Carefully analyze the functionality of each stylesheet and rule.
Look at the filter configuration on both channels (Publisher and Subscriber). This will help you understand the authoritative data sources.
Try to match the action that causes the error with the driver that caused it. Specifically, in this step you are trying to isolate the specific eDirectory or Application event that is causing the driver to generate the error.
Once you have identified the specific event and driver causing the error, take a closer look at the direction in which the error is being generated. If it is from the Application to eDirectory, the Publisher channel is involved. If it is from eDirectory to the Application, the Subscriber channel is involved. The problem could be in the Publisher or the Subscriber channel, or both.
Once you have identified the event and driver that is causing the problem, you need to drill down further to identify the stylesheet and/or rule that is likely causing the error.
Generate Required Trace File(s)
Earlier in this AppNote we talked about trace types and levels, along with the different tools that can be used to capture traces. It is time to practice what you have learned and gather some trace information. The general steps are as follows:
Identify the best trace method to use (DSTRACE, iMonitor, or Java Trace).
Decide which trace flag to use (DXML or DVRS).
Identify and set the trace level that is needed.
Isolate the trace to a specific driver. Since the traces are DRIVER-SET specific, it is important to try to narrow down the trace for easier troubleshooting.
If at all possible, turn off (running -> stopped) any drivers that are not causing the issue.
Note: If you can, it is preferable to stop the drivers rather than disabling them. There are some cases where you won't be able to turn off all other drivers-for example, the case of an event being worked on by one driver and a downstream driver having the error.
Start the trace, perform the action that causes the error, and then stop the trace.
Try to limit the trace to the specific action that causes the issue (as identified previously). For example, if you know that the deletion of a User object triggers the error, start the trace and then generate a User object delete to capture that process in the trace file.
Note: Remember that if the DirXML solution includes the eDirectory-to-eDirectory mirror driver, traces will need to be generated from both eDirectory trees.
Capturing a Trace When the Remote Loader Is In Use. The Remote Loader is new to DirXML 1.1. It allows DirXML drivers that must run on a particular platform to communicate with a DirXML engine running on a different platform. The reason we bring this up is that having a driver configured and using the Remote Loader allows you, by default, to capture a trace that is driver-specific.
Review the Trace File(s)
Once you have obtained the trace files you need, examine them thoroughly to determine what the cause of the problem is.
Find the error message in the trace file and see if you can determine the cause from the message alone; if not, continue with the steps below.
Find the beginning of the action that is causing the error. This is very important because often the problem is triggered by some action prior to where the error message is located in the trace file. It is critical to go back through the trace to where you see the initial XML document being received.
Compare the contents of the trace files with the stylesheets and rules as they are instantiated. From the trace files, you can determine where you are in the code.
Try to understand each segment of the trace file to the best of your ability before moving on to the next segment.
Never assume that a portion of the trace file is okay just because the error occurs later on in the trace file. Often errors arise because some set of criteria wasn't met previously.
Assume that something in the trace file is normal only if you are certain that it is, based on your knowledge and familiarity with the driver's functionality, rules, and stylesheets.
If you have not found the error or cause at this point, you may need to review the steps you took in generating the trace file. If your trace was too restrictive, you may need to repeat it with different settings. Common mistakes include the wrong selection of the trace type or trace level, or turning on a driver that affects a downstream driver. After you regenerate the trace file, review the new results by following the steps above.
Identify the Error and Its Cause
A careful reviewed of the trace files should give you a pretty good idea of what the error is and what might be causing it. Here are some questions to ask to further isolate the cause:
Application. Is there a problem with the application, its setup, or how it interacts with eDirectory?
Driver. Is there an issue with the driver itself in how it is designed to handle different event types?
eDirectory. Could there be eDirectory issues that may be causing the problems? (Examples include time synchronization issues, stuck obituaries, or incorrect replica placement.)
Rules. Is there a rule that may be misconfigured that is causing the error?
Stylesheets. Is there a stylesheet that is not written with sound logic?
Environment (network infrastructure and so on). Could there be communication issues that are causing events to be missed or corrupted?
For help on any error messages, refer to Novell's support knowledgebase at http://support.novell.com.
There have been instances where the issue identified is a fundamental flaw in the DirXML solution design. There have also been instances where the issue is a simple oversight in the implementation. If the issue is related to custom code in the DirXML implementation, you should review your findings with the developer of the solution.
Identify Possible Solutions
In DirXML there are many different ways to achieve a specific task. At this stage, you need to determine the different feasible solutions, understand each possibility, and determine the best candidate to be tested and implemented.
Identify all possible solutions for resolving the issue. Document the pros and cons of each one.
Identify the ramifications of each resolution. Changes in DirXML can be devastating if not carried out methodically. You must understand how a change in one area of DirXML can impact other drivers, applications, or other event types. From this you can appreciate the importance and requirement of carrying out end-to-end testing.
If the issue is a fundamental design flaw in the DirXML implementation, be sure that the appropriate individuals are notified and involved in the resolution. In many scenarios, this will involve the developers of the custom code.
All appropriate and qualified individuals must be involved to determine the proper solution. It is very helpful to recruit someone who understands the big picture.
If the DirXML implementation involves many different applications and drivers, make sure you plug your resolution into the overall picture. (Again you can see the need for end-to-end testing.)
Select the most appropriate solution to be tried. We cannot stress enough how important it is to test, test, and test some more before making final changes to the production environment.
DirXML Troubleshooting Example
To help bring together all the things you have learned thus far in this AppNote, let's work through an example of resolving an actual DirXML issue. The example scenario is this: Customer XYZ contacts you and reports that an error is occurring in their DirXML implementation. You are being asked to help troubleshoot a DirXML issue in an environment that you are not familiar with.
You ask the customer to describe the error. (You are trying to "Identify the General Issue.")
The customer explains that they sometimes receive a -609 error when creating users.
You ask yourself: Does this error give me any ideas at this point?
You know that the -609 error means Missing Mandatory Attributes. However, at this point you don't know what drivers are in use or why the error is intermittent. Since you don't yet have enough information, you must ask more questions.
You ask the customer to describe their environment and the current driver functionality. (You are gathering the required information for the "Understand the DirXML Environment" and "Understand the General Driver Functionality" stages.)
From the customer you learn the following:
The platform is NetWare 5.1 and DirXML 1.0.
The eDirectory-to-eDirectory mirror driver is being used.
No custom stylesheets have been implemented.
You also ask for exports of the drivers. Since the eDirectory-to-eDirectory driver is being used, two drivers are involved: one in each tree. Therefore you receive two reports.
You ask yourself: Am I ready to capture trace files at this point? (You are entering the "Generate Trace Files" stage.)
Since you don't yet know much about the problem, other than that it occurs "sometimes," you ask the customer for a more detailed description of when the error occurs. You learn that User objects created in Tree-A are not created in Tree-B. However, User objects created in Tree-B are created in Tree-A. User object modification works both ways with no errors.
You ask yourself: What trace type and level are needed?
Since the error only occurs when creating users in Tree-A, you determine that you need to capture a trace of a user being created in Tree-A, from both Tree-A and Tree-B. Since there is no XSLT, you only need the DVRS flag. The trace level should be set to 3 to capture all the information in the trace.
You generate the appropriate trace files, based on the above criteria.
You now go through the trace files looking for pertinent information (the "Review the Trace Files" stage).
Here is a portion of the trace file generated for Tree-B:
<nds dtdversion="1.1" ndsversion="8.5"> <source> <product version="1.1">DirXML</product> <contact>Novell, Inc.</contact> </source> <input> <add class-name="User" src-dn="\TREE-A\novell\Users\JDoe"> <add-attr attr-name="CN"> <value>JDoe</value> </add-attr> </add> </input> </nds> Driver = \TRE-B\novell\servers\driver-set\NDSToNDS - Mirror Channel = publisher Object = \TREE-A\novell\Users\JDoe (\TREE-B\novell\users\JDoe) Message = createEntry: -609 ERR_MISSING_MANDATORY
In reviewing this trace file, you first find the -609 error (in bold above). You notice that what seems to be causing the error is that the XML Add document being submitted to the engine is missing the <Surname> attribute.
Since you're dealing with an eDirectory-to-eDirectory implementation, both drivers should have the same required attributes. The <Surname> attribute was certainly there when the user was created in Tree-A. So from this you infer that something between the create in Tree-A and Tree-B is removing the <Surname> attribute.
You ask yourself: Do I have any ideas as to how to proceed?
Since filters are generally used to remove specific attributes, a logical next step would be to check the filters. The error only occurs when creating user objects in Tree-A, so you should check the Subscriber filter in Tree-A and the Publisher filter in Tree-B.
You could also check the trace file above (from Tree-B) and see if the initial document has the <Surname> attribute. If it does, that would indicate the Tree-B Publisher filter removed it. If the initial document doesn't have the <Surname> attribute, you can conclude that the Subscriber Filter in Tree-A removed it.
You review the beginning of the trace file from Tree-B to confirm which filter may be causing the problem.
TRACE: NdsToNds Publisher - NDSToNDS - Mirror: Receiving... TRACE: NdsToNds Publisher - NDSToNDS - Mirror: Received. TRACE: NdsToNds Publisher - NDSToNDS - Mirror: XML Document: TRACE: <nds dtdversion="1.1" ndsversion="8.5"> <source> <product version="1.1">DirXML</product> <contact>Novell, Inc.</contact> </source> <input> <add class-name="User" src-dn="\TREE-A\novell\Users\JDoe"> <add-attr attr-name="Surname"> <value>Doe</value> </add-attr> <add-attr attr-name="CN"> <value>JDoe</value> </add-attr> </add> </input> </nds> TRACE: Receiving DOM document from app
From this you see that the <Surname> attribute was present in the initial Add document that Tree-B received. You conclude that the problem must be in the filter of the Publisher channel in Tree-B.
To confirm whether your assumption is correct, you now check the Publisher filter in Tree-B (see Figure 10).
Figure 10: Checking the Publisher filter.
From the Publisher Filter image, you learn that the <Surname> attribute is in the filter, and therefore your assumption is wrong. You must now review the trace files that include the capturing of XSLT information.
You carefully review the trace file from the beginning and find the following lines in your trace file:
TRACE: Applying input transformations TRACE: Applying input stylesheet TRACE: Applying stylesheet based rule TRACE: Rule stylesheet returned:
You notice the line "Applying input stylesheet" which indicates that an input stylesheet is in place, since it is being executed. The customer told you there are no custom stylesheets in place, yet here you see that DirXML is applying an input transformation stylesheet.
You now review the driver export of Tree-B, where you find the following input transformation rule:
<?xml version="1.0" encoding="UTF-8"?> <xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"> <xsl:template match="/"> <xsl:apply-templates select="node()|@*"/> </xsl:template> <xsl:template match="node()|@*"> <xsl:copy> <xsl:apply-templates select="node()|@*"/> </xsl:copy> </xsl:template> <xsl:template match="add-attr[@attr-name='Surname']"/> </xsl:stylesheet>
The statement <xsl:template match="add-attr[@attr-name='Surname']"/> matches on the event of adding an attribute that has an attribute name of "Surname" and then does nothing. (For those who are familiar with XSLT, this is how you would go about stripping the Surname attribute from a XML document.) So it is this line in this stylesheet that is removing the Surname attribute from the XML document and is thereby causing the -609 error. You have now identified the cause of the problem (thus completing the "Identify the Error and Its Cause" stage)!
You now proceed to "Identify Possible Solutions" for this issue.
As with any problem, there can be many different solutions. For the problem you have identified there are two solutions, each with its pros and cons.
One solution would be to remove the offending template from the Input Transformation Rule.
Pro: This would eliminate the root cause of the surname being stripped from the Add document.
Con: Unless you know why the template was placed there to begin with, you can't simply remove it. Doing so without understanding why it was there could introduce other issues.
A second solution would be to synthesize or build the Surname from another attribute. There are different ways to do this; one method would be to try to deduce the Surname from the CN.
Pro: This solution really has no pros, even though it can solve the problem.
Con: Since you don't know why the template was placed in the stylesheet, any type of workaround could have other ramifications that might introduce a new set of problems. In addition, this particular solution isn't the most efficient since it would require significant recoding to fix a seemingly simple issue.
Unless you are the developer who was involved in the initial implementation, or someone who thoroughly understands the environment, you're probably not the individual best qualified to implement either of these possible solutions-especially because you don't know what the initial intention was of having that template statement in the stylesheet.
You contact the developer and implementation team that initially set up the environment and engage in a discussion to determine the best possible solution. Once you have the solution, you perform end-to-end testing before making changes to the production environment.
Hopefully by going through this example, you have observed the natural progression through the stages of the DirXML troubleshooting methodology.
Conclusion
This AppNote has reviewed the different tools commonly used to troubleshoot DirXML issues, introduced a DirXML troubleshooting methodology, and presented an example troubleshooting scenario. A follow-up AppNote will expand on what you have learned, providing additional details on how to effectively read a DirXML trace file.
* Originally published in Novell AppNotes
Disclaimer
The origin of this information may be internal or external to Novell. While Novell makes all reasonable efforts to verify this information, Novell does not make explicit or implied claims to its validity.