1. www.novell.com Avoiding the Top DirXML ™ Issues Sandy Swanson WSS Engineer Novell, Inc. sswanson@novell.com

2. Vision…one Net A world where networks of all types—corporate and public, intranets, extranets, and the Internet—work together as one Net and securely connect employees, customers, suppliers, and partners across organizational boundaries Mission To solve complex business and technical challenges with Net business solutions that enable people, processes, and systems to work together and our customers to profit from the opportunities of a networked world

4. Agenda Troubleshooting tools  Trace Commands and Trace Files  NXSL Processor  Troubleshooting methodology  Troubleshooting sample  How to read a trace log

5. Trace Commands and Trace Files Trace options  DSTRACE.NLM Easy and familiar It can slow down DirXML™ if used excessively  iMonitor Easy to use and will display real-time activity remotely May truncate large XML documents (versions prior to 1.5) so it may not be suitable for detailed troubleshooting  Javatrace File Won’t show real-time activity Won’t show details about cache files, driver start and stop No auto-roll or Max size so it can fill your drive if not monitored Best option for detailed troubleshooting of driver functionality

6. Trace Commands and Trace Files (cont.) Trace levels are set on the driver-set (not per driver)  DirXML-DriverTraceLevel is used to troubleshoot driver issues  DirXML-XSLTTraceLevel is used to troubleshoot XSLT issues (don’t use unless you are developing or troubleshooting stylesheet code) How to enable Trace Levels DirXML-XSLTTraceLevel can be interchanged with DirXML- DriverTraceLevel in the following instructions In ConsoleOne ®, right-click a DirXML-Driver Set object Click Properties > Other Double-click DirXML-DriverTraceLevel in the Attributes list If DirXML DriverTraceLevel doesn’t appear in the Attribute list, click Add and select the attribute Enter 0 to 3 in the text box below DirXML-DriverTraceLevel

7. XSLT Trace Level Details ValueDescription 0 No trace messages are displayed or logged 1 Trace source node processing, output to standard error 2 Trace the above plus rule instantiations 3 Trace the above plus template instantiations 4 Trace the above plus rule matching and select expression details

8. DVRS Trace Level Details ValueDescription 0 No trace messages are displayed or logged 1 Basic trace messages are displayed and logged 2 Level 1 messages and the contents of XML documents used during event processing are displayed and logged 3 Level 2 messages and extensive rule processing messages are displayed and logged

9. Trace Commands and Trace Files DSTrace Commands  NetWare ® LOAD DSTRACE DSTRACE –ALL DSTRACE + DVRS (to troubleshoot Drivers) DSTRACE + DXML (to troubleshoot XSLT Code) DSTRACE file on (to log to sys:system\dstrace.dbg) DSTRACE screen on (to display live trace on server console)

10. Trace Commands and Trace Files (cont.) DSTrace Commands  NetWare LOAD DSTRACE DSTRACE –ALL DSTRACE + DVRS (to troubleshoot Drivers) DSTRACE + DXML (to troubleshoot XSLT Code) DSTRACE file on (to log to sys:system\dstrace.dbg) DSTRACE screen on (to display live trace on server console)

11. Trace Commands and Trace Files (cont.) DSTrace Commands  Windows NT/2000 Start DSTRACE.DLM from Novell eDirectory™ Services (NDSCONS.EXE) Edit, Options, Clear All Check DirXML Drivers (to troubleshoot Drivers) Check DirXML (to troubleshoot XSLT Code) File, New, enter File Name (to log to file)

12. Trace Commands and Trace Files (cont.) DSTrace Commands  UNIX/Linux start ndstrace set dstrace = nodebug (to clear all other trace options) set dstrace = + dvrs (to troubleshoot Drivers) set dstrace = + dxml (to troubleshoot XSLT Code) Dstrace file on (to log to file /var/nds/DSTRACE.LOG)

13. Trace Commands and Trace Files (cont.) How to enable Java Trace File In ConsoleOne, right-click a DirXML-Driver Set object Click Properties > Other Double-click DirXML-JavaTraceFile in the Attributes list If DirXML-JavaTraceFile doesn’t appear in the Attribute list, click Add and select the attribute Enter the path in the text box below DirXML- JavaTraceFile –On NetWare use volume:/path/filename (i.e. SYS:TEMP\JAVATRACE.TXT) –On Win32 use Drive:\path\filename (i.e. C:\temp\JAVATRACE.TXT) –On UNIX use /path/path/filename (i.e. /var/nds/JAVATRACE.TXT)

14. NXSL Processor The NXSL Processor provides the ability to use Novell XSL Processor outside DirXML To run the NXSL processor, perform the following steps 1. Install JRE 1.3.1 from Sun Microsystems 2. Copy RT.JAR, NXSL.JAR, COLLECTIONS.JAR and XP.JAR into a directory 3. Copy the following text into a batch file in your NXSL Directory @echo off setlocal rem set JAVA_HOME to your JRE or JDK directory SET JAVA_HOME=C:\jdk1.3.1_01\jre SET NXSL_JARS=C:\novell\xsl rem set NXSL_JARS to the location containing nxsl.jar, xp.jar, and collections.jar set CLASSPATH=%JAVA_HOME%\lib\rt.jar set CLASSPATH=%CLASSPATH%;%NXSL_JARS%\nxsl.jar;%NXSL_JARS%\collections.jar set CLASSPATH=%CLASSPATH%;%NXSL_JARS%\xp.jar set nxsl=%JAVA_HOME%\bin\java -classpath %CLASSPATH% com.novell.xsl.nxsl %nxsl% -e1 %1 %2 %3 %4 %5 %6 %7 %8 endlocal

15. NXSL Processor (cont.) Use NXSL Processor to troubleshoot the following  Validate XSLT Logic  Check for well formed XML/XSLT documents  Test stylesheet in different event types and scenarios to ensure that all events are handled  Test stylesheets without affecting production/test tree

16. NXSL Processor (cont.) Don’t use NXSL Processor to troubleshoot the following  Stylesheets with Queries in them  Check for well-formed XDS documents  Test Rules/Stylesheet interaction  Not valid for end-to-end testing Only testing the XSLT logic Not testing Application/eDirectory-specific issues

17. NXSL Processor (cont.) To process a source XML document with a stylesheet nxsl source.xml stylesheet.xsl Will output Result tree to Standard Out nxsl –o result.xml source.xml stylesheet.xsl Will output Result tree to file RESULT.XML nxsl –d[1-4] source.xml stylesheet.xsl Will generate detailed trace messages (see XSLTTracelevel for description)

18. Troubleshooting Methodology  Identify general issue  Understand DirXML environment  Understand general driver functionality  Generate trace file  Review trace file carefully  Identify error and its cause  Identify possible solutions At any point, if you have a strong hunch (based on your experience or knowledge) spend a few minutes following that hunch but always return to the method if that hunch does not pan out; don’t get side tracked by it Remember to use the KIS principle “Keep It Simple;” most problems when broken down are one to many simple problems

19. Troubleshooting Methodology (cont.)  Identify general issue Driver not starting Driver stopping unexpectedly Rules not functioning as expected Stylesheets not functioning as expected Unexpected output/results Unexpected eDirectory Error Codes Identify/isolate what action causes the issue (important) –Starting driver –Stopping driver –Creating users –Deleting users –Moving users –Running driver for specific amount of time

20. Troubleshooting Methodology (cont.) Understand DirXML environment  Identify platform/product versions in use  Identify DirXML Drivers in use  Understand basic data flow  Identify outstanding eDirectory issues (if applicable)  Understand Replica Placement  Obtain Driver Exports and import into Test Tree for review

21. Troubleshooting Methodology (cont.) Understand general driver functionality  Review driver exports/documentation Understand functionality that each stylesheet/rule provides Understand filter configuration  Match action that caused error with driver that caused it Identify Channel that causes the error Identify the stylesheet/rule that is likely causing the error

22. Troubleshooting Methodology (cont.) Generate trace file  Identify trace method (dstrace, javatrace or iMonitor)  Identify trace flags (DXML or DVRS)  Identify trace level that is needed  If eDirectory to eDirectory, you may need traces from both sides  Don’t assume default configuration is used, always ask  Isolate trace to specific driver Turn off any drivers that are not causing the issue Try and limit the trace to to specific action that causes the issue (as identified previously)  Perform action that causes issue and then stop trace

23. Troubleshooting Methodology (cont.) Review trace file carefully  Find error message in trace and see if you can determine the cause from that message alone; if not, continue below  Find beginning of action that caused the error  Compare contents with stylesheets/rules as they are instantiated  Try and understand each segment of the trace before moving to the next segment  Don’t assume it’s OK just because the error happens later  Don’t assume it’s normal unless you are certain that it is  If you don’t see the error or cause then you may need to review the steps taken to isolate the trace (may have been too restrictive)

24. Troubleshooting Methodology (cont.) After identifying error and its cause  Identify if error is caused by Application eDirectory Rules Driver Stylesheet Environment (replica placement, infrastructure, etc.)  If possible, review findings with developer of solution  Identify if the issue is a fundamental flaw in solution design or is it a simple oversight

25. Troubleshooting Methodology (cont.) Identify possible solutions  Identify all possible methods of resolving the issue  Identify ramifications of each resolution  If issue is fundamental design flaw be sure that the appropriate people are notified and involved in the resolution  Make sure you are qualified to determine proper solution (if not, you must involve appropriate individuals)  Make sure you plug your resolution into the overall picture  Once you’ve chosen a solution TEST, TEST and TEST some more before making the change in production

26. Troubleshooting Methodology (cont.) Error is reported Any ideas? Yes Identify general issue Understand DirXML environment No Understand General Driver Functionality Generate isolated trace log Glance at error message Yes Carefully review trace File with stylesheets No Any ideas? Yes Review trace Isolation— To narrow? No Follow your hunch and verify Were you correct? Have you tested it? No Yes

27. DirXML Architecture Application or directory or database eDirectory datastore DirXML Join engine Application Shim eDirectory Interface Filter M C P C 1.1 S O Rules and stylesheets C 1.1 P C M E S Rules and stylesheets xxxxx.tao Subscriber Subscriber E I eDirectory event eDirectory formatted XML ANF XML to NDS XML ANF formatted XML Apply to app App event ANF formatted XML NDS XML to ANF XML Filter eDirectory formatted XML Apply to eDirectory Publisher

28. Troubleshooting Sample Customer reports an error 1. Ask customer to describe error (identify general issue) Customer is sometimes getting -609 error when creating users 2. Does that mean anything to you? -609 error means Missing Mandatory Attributes, however, we don’t know what drivers are in use and we don’t know why it only happens ‘sometimes’ 3. Ask customer to describe environment and driver functionality Customer is using eDirectory to eDirectory mirror (no custom stylesheets) on NetWare 5/DirXML 1.0 4. Are you ready to get a trace No—customer said “sometimes” and you have not determined when 5. Ask customer to describe when error happens Customer says users created in Tree-A are not created in Tree-B—users created in Tree-B are created in Tree-A, however, modifications work both ways

29. Troubleshooting Sample (cont.) 6. What trace do you think you need? Since it only happens when creating users in Tree-A, let’s start with a trace on Tree-B side, of a user being created in Tree-A. Only need DVRS flag since there is no XSLT 7. Generate appropriate Trace DirXML Novell, Inc. JDoe 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

30. Troubleshooting Sample (cont.) 7. Glance at trace—does anything catch your eye? You notice that the document that is submitted to the engine is missing the attribute, which is generating the –609 8. Any clues? You should have guessed that since it’s eDirectory to eDirectory, both drivers will have the same required attributes so the was certainly there when the user was created in Tree-A—something between the create in Tree-A and Tree-B is removing the 9. Next steps? Since Filters are generally used to remove specific attributes, your first step would be to check them—since the error is only when creating users in Tree-A, you should check the Subscriber Filter in Tree-A and the Publisher Filter in Tree-B You can also check the same log and see if the initial document had the which would indicate that the Tree-B Publisher Filter removed it—if the initial document did not have the then the Subscriber Filter in TREE-A removed it

31. Troubleshooting Sample (cont.) 10. Review beginning of trace to confirm which filter TRACE: NdsToNds Publisher - NDSToNDS - Mirror: Receiving... TRACE: NdsToNds Publisher - NDSToNDS - Mirror: Received. TRACE: NdsToNds Publisher - NDSToNDS - Mirror: XML Document: TRACE: DirXML Novell, Inc. Doe JDoe TRACE: Receiving DOM document from app Since the Surname was present in initial document, the issue must be caused by TREE-B Publisher Filter Right?

32. Troubleshooting Sample (cont.) 11. Check Publisher Filter to confirm your hunch Oops! Our hunch was wrong; Surname is present in the filter—we need to review trace with stylesheets

33. Troubleshooting Sample (cont.) 12. Carefully review trace from top Upon careful review you 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: The statement was that “they had no custom stylesheets” Yet we see DirXML applying an Input Transformation stylesheet

34. Troubleshooting Sample (cont.) <xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"> 13. Carefully review driver export of Tree-B Upon careful review you find the following Input Transformation Rule Somebody added an Input Transformation Rule that filters out add add-attr elements for Surname This is causing your -609

35. Troubleshooting Sample (cont.) 14. Identify possible solutions a)Remove that template from the Input Transformation Rule Pro: Eliminate the root cause Con: Do you know why it was placed there to begin with? If not, then you can’t simply remove it b)Synthesize the Surname from another attribute Pro: None Con: Still don’t know the reason it was coded so any work around is suspect—in addition, this particular solution is a kludge because you added significant code to work around a seemingly simple issue 15. Are you qualified implement the solution Unless you are the developer, you are not qualified to implement the solution above since you don’t know what the initial intention was 16. Contact the Developer Contact developer that was responsible for the initial deployment and engage them in a discussion

36. How to Read a Trace Log When carefully reviewing a trace, keep these in mind  Don’t assume anything is OK You will learn with experience which errors are normal Until then, investigate every error  Understand every line before proceeding to the next Again, you will learn with experience what each line means The best way to learn how the DirXML engine works is to analyze the trace logs  Have the driver exports at hand Have the driver-exports handy as you review the traces Correlate the actions in the trace logs with the rules/stylesheets in the export

37. Sample Trace Log The next few slides will show a sample tracelog with no errors and explain the content

38. Sample Trace Log—Subscriber Initial create of the user in the DIB [01/07/02 12:13:17.912]: TRACE: Commit transaction requested [01/07/02 12:21:36.196]: TRACE: Start transaction [01/07/02 12:21:36.196]: TRACE: submitEvent requested [01/07/02 12:21:36.196]: TRACE: event for attr: null [01/07/02 12:21:36.196]: TRACE: created a DOM node for event [01/07/02 12:21:36.196]: TRACE: submitEvent requested [01/07/02 12:21:36.196]: TRACE: event for attr: ACL [01/07/02 12:21:36.196]: TRACE: created a DOM node for event ……… [01/07/02 12:21:36.416]: TRACE: Processing events for transaction [01/07/02 12:21:36.416]: TRACE: Converting \NW6-TREE\novell\Users\James Dean from Unknown to real base class The above messages represent DirXML detecting changes to the eDirectory Database for which DirXML events must be generated—Once those changes are complete, DirXML will trigger it’s event to send down the Subscriber Channel

39. Sample Trace Log—Subscriber (cont.) Once the user is created in the DIB, DirXML issues an event for that ADD DirXML Novell, Inc. Dean Jimmy James Dean

40. Sample Trace Log—Subscriber (cont.) DirXML now takes that add Document and sends it down the Subscriber channel, processing each rule as it hits that rule [01/07/02 12:21:36.416]: TRACE: No event transformation rule, skipping [01/07/02 12:21:36.416]: TRACE: Subscriber processing add for \NW6- TREE\novell\Users\James Dean (This is the Association Processor checking to make sure we synthesize an ADD event if this was a modify on an un-associated object) [01/07/02 12:21:36.416]: TRACE: Re-reading associations in case they changed since this event was queued (Double checking to see that the object is not associated) [01/07/02 12:21:36.416]: TRACE: No matching rule, skipping [01/07/02 12:21:36.416]: TRACE: No create rule, skipping [01/07/02 12:21:36.416]: TRACE: No placement rule, skipping [01/07/02 12:21:36.470]: TRACE: Submitting add to subscriber shim

41. Sample Trace Log—Subscriber (cont.) (Completed Channel specific transformation—Now DirXML applies the Schema and Output Transformation rules) [01/07/02 12:21:36.470]: TRACE: Applying output transformations [01/07/02 12:21:36.470]: TRACE: Fixing up associations references [01/07/02 12:21:36.470]: TRACE: No mapping rule, skipping [01/07/02 12:21:36.470]: TRACE: No output stylesheet, skipping [01/07/02 12:21:36.470]: TRACE: Submitting document to subscriber shim (Once all transformations are complete on this channel, DirXML sends the transformed document to the Driver Shim to send to the remote database)

42. Sample Trace Log—Subscriber (cont.) [01/07/02 12:21:36.470]: TRACE: NdsToNds Subscriber - NDSToNDS - Flat: Reusing connection. [01/07/02 12:21:36.470]: TRACE: NdsToNds Subscriber - NDSToNDS - Flat: Sending... [01/07/02 12:21:36.470]: TRACE: NdsToNds Subscriber - NDSToNDS - Flat: XML Document: [01/07/02 12:21:36.470]: TRACE: Again, just showing what the shim sent to the destination tree DirXML Novell, Inc.

43. Sample Trace Log—Subscriber (cont.) Dean Jimmy James Dean (This is the document after all the transformation completed and as it will appear to the remote database)

44. Sample Trace Log—Subscriber (cont.) [01/07/02 12:21:36.470]: TRACE: NdsToNds Subscriber - NDSToNDS - Flat: Document sent. [01/07/02 12:21:36.470]: TRACE: NdsToNds Subscriber - NDSToNDS - Flat: Waiting for receive... Now DirXML has send the document and waiting for a response—At this point, since it’s eDirectory to eDirectory we could pause here and read the other trace, since there may be some additional transformation done on that side

45. Sample Trace Log—Publisher (cont.) [01/07/02 12:15:11.981]: TRACE: Commit transaction requested [01/07/02 12:20:37.920]: TRACE: NdsToNds Publisher - NDSToNDS - Flat: Receiving... [01/07/02 12:20:37.930]: TRACE: NdsToNds Publisher - NDSToNDS - Flat: Received. [01/07/02 12:20:37.930]: TRACE: NdsToNds Publisher - NDSToNDS - Flat: XML Document: [01/07/02 12:20:37.950]: TRACE: DirXML Novell, Inc.

46. Sample Trace Log—Publisher (cont.) Dean Jimmy James Dean

47. Sample Trace Log—Publisher (cont.) (Here DirXML starts applying the Input Transformation and Schema Mapping Rule, which are not present) [01/07/02 12:20:37.960]: TRACE: Applying input transformations [01/07/02 12:20:37.970]: TRACE: No input stylesheet, skipping [01/07/02 12:20:37.970]: TRACE: No mapping rule, skipping [01/07/02 12:20:37.970]: TRACE: Resolving association references [01/07/02 12:20:37.980]: TRACE: No event transformation rule, skipping (Here DirXML checks to see if this object is already associated) [01/07/02 12:20:37.990]: TRACE: No associated objects [01/07/02 12:20:37.990]: TRACE: Applying publisher filter [01/07/02 12:20:37.990]: TRACE: Publisher processing add for \NW6- TREE\novell\Users\James Dean

48. Sample Trace Log—Publisher (cont.) (Here DirXML tries the matching rule, and queries NDS based on the matching rule) [01/07/02 12:20:37.990]: TRACE: Applying matching rule [01/07/02 12:20:38.00]: TRACE: Pumping XDS to NDS [01/07/02 12:20:38.10]: TRACE: Performing operation, op: query for: novell\Users [01/07/02 12:20:38.10]: TRACE: (Since no results are returned, DirXML assumes that no match was found proceeds with the Create Rule) [01/07/02 12:20:38.10]: TRACE: No match found (The Create rule is checked and the ADD is not vetoed) [01/07/02 12:20:38.10]: TRACE: Applying create rule [01/07/02 12:20:38.10]: TRACE: Trying create rule 1 [01/07/02 12:20:38.10]: TRACE: Rule selected

49. Sample Trace Log—Publisher (cont.) (Next, DirXML applies the Placement Rule and selects the Destination Container the attempts to create the User) [01/07/02 12:20:38.10]: TRACE: Applying placement rule [01/07/02 12:20:38.10]: TRACE: Trying placement rule 1 [01/07/02 12:20:38.10]: TRACE: Rule selected [01/07/02 12:20:38.10]: TRACE: Placing object at: novell\Users\James Dean [01/07/02 12:20:38.10]: TRACE: Pumping XDS to NDS [01/07/02 12:20:38.10]: TRACE: Performing operation, op: add for: novell\Users\James Dean [01/07/02 12:20:38.20]: TRACE: Adding entry: novell\Users\James Dean [01/07/02 12:20:38.20]: TRACE: Creating RDN: James Dean in context: novell\Users (Since the User was created without errors, DirXML Logs a Success message) DirXML Log Event ------------------- Driver = \DXML11-TREE\novell\servers\driver-set\NDSToNDS - Flat Channel = publisher Object = \NW6-TREE\novell\Users\James Dean (novell\Users\James Dean) Status = success

50. Sample Trace Log—Publisher (cont.) (In addition to Sending a Success document to the Original Tree, DirXML adds the element so that the Original Tree updates it’s Association value) [01/07/02 12:20:38.281]: TRACE: Applying output transformations [01/07/02 12:20:38.281]: TRACE: Fixing up associations references (Since the Success document is being transmitted, it must go through the Output Transformation and Mapping rule) [01/07/02 12:20:38.281]: TRACE: No mapping rule, skipping [01/07/02 12:20:38.281]: TRACE: No output stylesheet, skipping [01/07/02 12:20:38.281]: TRACE: NdsToNds Publisher - NDSToNDS - Flat: Sending... [01/07/02 12:20:38.281]: TRACE: NdsToNds Publisher - NDSToNDS - Flat: XML Document:

51. Sample Trace Log—Publisher (cont.) DirXML Novell, Inc. {0090A600-9303-d611-A4CF-00C04F803492} [01/07/02 12:20:38.321]: TRACE: NdsToNds Publisher - NDSToNDS - Flat: Document sent. [01/07/02 12:20:38.321]: TRACE: NdsToNds Publisher - NDSToNDS - Flat: Reusing connection [01/07/02 12:20:38.321]: TRACE: NdsToNds Publisher - NDSToNDS - Flat: Waiting for receive... (The Add is complete from the Publisher Side)

52. Sample Trace Log—Subscriber (cont.) (Here the Subscriber Channel receives the Success and document from the Destination Tree) [01/07/02 12:21:36.910]: TRACE: NdsToNds Subscriber - NDSToNDS - Flat: Receiving... [01/07/02 12:21:36.910]: TRACE: NdsToNds Subscriber - NDSToNDS - Flat: Received. [01/07/02 12:21:36.910]: TRACE: NdsToNds Subscriber - NDSToNDS - Flat: XML Document: [01/07/02 12:21:36.910]: TRACE: SubscriptionShim.execute() returned: [01/07/02 12:21:36.910]: TRACE: DirXML Novell, Inc. {0090A600-9303-d611-A4CF-00C04F803492}

53. Sample Trace Log—Subscriber (cont.) (Since this is an incoming document it must be processed by the Input Transformation and Schema Mapping rule) [01/07/02 12:21:36.910]: TRACE: Applying input transformations [01/07/02 12:21:36.910]: TRACE: No input stylesheet, skipping [01/07/02 12:21:36.910]: TRACE: No mapping rule, skipping [01/07/02 12:21:36.910]: TRACE: Resolving association references

54. Sample Trace Log—Subscriber (cont.) (DirXML sees the Success document and then processes the and updates the association in the Source tree) [01/07/02 12:21:36.910]: TRACE: Handling returned document [01/07/02 12:21:36.910]: TRACE: Handling operation, op: status for: DirXML Log Event ------------------- Driver = \NW6-TREE\novell\servers\driver-set\NDSToNDS - Flat Channel = subscriber Object = \NW6-TREE\novell\Users\James Dean Status = success [01/07/02 12:21:36.910]: TRACE: Handling operation, op: add-association for: \NW6- TREE\novell\Users\James Dean (From the Subscriber Channel, this event is complete)