DeveloperNet University Home > Online Courses > Introduction to DirXML

eBook (Printable PDF format)

DirXML Lab 2

Welcome to the DirXML Overview course Lab 2. In this lab you will install and setup a fictitious application described as a PBX simulator. This will act as the application that you want to synchronize data to and from eDirectory with. A custom DirXML driver will be used to interface between the DirXML engine and the PBX simulator application.

Install the PBX driver

The PBX Simulator is a user information database. The PBX DirXML driver once installed, will synchronize that database with eDirectory, sending new and deleted information as a result of the commands issued either at the PBX application or ConsoleOne.

Figure 47: The PBX simulator application interface.

PBX Simulator

Requirements and Installation

1. Download DirXMLLabs.zip by selecting the download button on the bottom of the screen.
   
   
2. Install the PBX driver database structure and files. Unzip DirXMLLabs.zip to C:\ (or other) drive.
   
   
3. Create the following DirXML objects in your eDirectory tree with ConsoleOne.
   
   

   Note:

   Your tree, organization, server, or driver set may be named differently. Substitute the names accordingly.
   
   

Figure 48: Schema for PBX simulator application.

1. If you have not created a driver set, do so.
   
   
2. Create a DirXML driver object "Lab1Driver".
   
   
3. Inside the Lab1Driver, create the following objects; create a publisher "Lab1Publisher", a subscriber "Lab1Subscriber", and a rule "Lab1MappingRule".
   
   
4. Inside the Lab1Publisher, create 2 rules; "Lab1PubCreate" and "Lab1PubPlacement".
   
   
5. Inside the Lab1Subscriber, create 3 rules; "Lab1SubCreate", "Lab1SubMatching", and "Lab1SubPlacement".
   
   
6. Create the following OUs; "Provo" and "Orem". Create 2 OUs inside of Orem; "Engineering" and "Finance". Create 2 OUs inside of Provo; "Engineering" and "Education".
   
   

Installing the Driver

4. Make the following changes to the C:\DirXMLCrsFldr\Lab1Driver\sources\Lab1DriverShim.java" file:
   
   
5. If your labs are installed on a drive other than "C:," you must change the reference to "C:" in "Lab1DriverShim.java" to the correct drive letter before you build.
   
   
6. If your tree name is not "TESTTREE," you must change the reference to "TESTTREE" in "Lab1DriverShim.java" to the appropriate tree name before you build.
   
   

Open each of the following three .java files in "C:\DirXMLCrsFldr\Lab1Driver\sources\ " directory with Notepad and examine them. Set the font to Courier (a non-proportional font) so that things line up properly.

Lab1DriverShim.java
Lab1PublicationShim.java
Lab1SubscriptionShim.java

As you see, each implement an interface for a shim required by the DirXML driver (a driver implementation shim, a Publisher implementation shim, and a Subscriber implementation shim). The interface classes for these shims are located in "C:\DirXMLCrsFldr\Lab1Driver\sources\vrd.jar."

1. Open a Command window (equivalent to the DOS window on Windows 98) and cd to "C:\DirXMLCrsFldr\Lab1Driver\sources\."
   
   
2. Type "build" in the DOS window to execute the build.bat file in the "sources" directory. A file named "Lab1Driver.jar" will be created in the "sources" directory. This .jar file contains the shim classes compiled from the java sources you viewed earlier.
   
   

   Note:

   Every time you change a .JAR file (recompile), you must shut down and restart eDirectory. This is because the Java Virtual Machine caches all classes at start-up. If you don't restart, your new .JAR files will never be loaded.
   
   

3. Copy the Lab1Driver.jar file to the "C:\Novell\NDS\lib" directory on your machine. eDirectory was installed in the "C:\Novell\NDS\" directory.
   
   
4. Copy the pbx.jar file from your course directory to the "C:\Novell\NDS\lib" directory on your machine. This JAR file contains the classes for the PBXSimulator application and must be located in the Lib directory so that the lab driver can load it.
   
   
5. Copy the swing.jar file from your course directory "c:\DirXMLCrsFldr" to the "C:\Novell\NDS\lib" directory on your machine. This JAR file contains the Java classes for the GUI in the PBXSimulator application and must be located in the Lib directory so that PBXSimulator can load it.
   
   
5. Configure eDirectory objects inside of "Lab1Driver" to fully define the Lab1 DirXML-Driver.
   
   

   Note:

   In the following steps, you will be asked to copy the contents of .xml and .xsl files into DirXML eDirectory objects. Don't open the source files in a browser. Use Notepad or a similar application instead. Copied text from a browser window will include invisible characters that interfere with DirXML's ability to parse the information.
   
   

Completely delete all existing text from each eDirectory object before copying xml\xsl source data into it.

If the tree name on your workstation is not TESTTREE, then you will need to change all references to TESTTREE in pubPlacementRule.xml to refer to the correct tree.

In the following step, as you create and populate the mapping rule, the dialog below may appear. Ignore the dialog if it appears.

Figure 49: Reading the application's schema dialog box.

1. In ConsoleOne, open properties for each of the object's listed below. Then click the down arrow in its "DirXML" tab and select "Edit XML" to display each edit field for copy. Open each .xml file in the c:\DirXMLCrsFldr\Lab1Driver\sources\rules with Notepad, copy, then paste it in the corresponding driver rule. After each copy in ConsoleOne, click "Apply" to commit the new data:
   
   

MappingRule.xml -> Lab1MappingRule.Lab1Driver

pubPlacementRule.xml -> Lab1PubPlacement.Lab1Publisher.Lab1Driver

pubCreateRule.xml -> Lab1PubCreate.Lab1Publisher.Lab1Driver

subMatchingRule.xml -> Lab1SubMatching.Lab1Subscriber.Lab1Driver

subCreateRule.xml -> Lab1SubCreate.Lab1Subscriber.Lab1Driver

subPlacementRules.xml -> Lab1SubPlacement.Lab1Subscriber.Lab1Driver

1. Add the Server object to the DirXML-DriverSet. Right-click the MyDriverSet object and select properties. Click the DirXML tab until a drop-down-menu appears. Select "Server" in the menu to display the driver set's Server page as shown in figure below.
   
   

Figure 50: Properties of MyDriverSet edit window.

6. Select "Add" to browse for the eDirectory Server object's you are using. Click "Apply" and then "Close" to commit your changes.
   
   
7. Select the security proxy for your driver objects. Right-click Lab1Driver->Properties and select the "Memberships" tab as shown in Figure 51.
   
   

Figure 51: Security proxy membership.

7. Select "Add" to browse and select "Admin.Novell." Click "Apply" and then "Close" to commit your changes.
   
   
8. Associate the Lab1 driver's shim class with the "Lab1Driver" eDirectory object. Right-click Lab1Driver->Properties, select the "DirXML" tab until a menu appears. Select "Driver Configuration" in the menu as shown in figure below.
   
   

Figure 52: Driver configuration.

8. Select "Java" for executable type. Type the case sensitive name of the class implementing the driver shim, "Lab1DriverShim." Do not enter the ".class" suffix of the name. This class is located in the Lab1Driver.jar file you put in the c:\Novell\NDS\Lib directory. Click "Apply" and then "Close" to commit your changes.
   
   
9. Define the filter sets to be used by the Lab1 driver. The filter sets define the class and attribute types that are allowed to pass.
   
   

The Publisher filter defines the object and attribute types that can be published to the eDirectory tree. The Subscriber filter can be completely different from the Publisher filter because you may be pushing completely different objects and attributes out from eDirectory to the external system than you are receiving from it.

9. Right-click Lab1Publisher->Properties and select the "DirXML" tab, then select "Filter". Click "Edit Filter" and select the "User" class and add the filter attributes below.
   
   

Figure 53: Adding filter attributes of User for Publisher.

10. Click "OK" to close the "Edit" window. Then click "Apply" and then "Close" to commit your changes.
    
    
11. Right-click Lab1Subscriber->Properties and select the "DirXML" tab, then select "Filter". Click "Edit Filter" and select "User" class and add the filter attributes below.
    
    

Figure 54: Adding filter attributes of User for Subscriber.

12. Click "OK" to close the "Edit" window. Then click "Apply" to commit your changes.
    
    

In the "Filter" property page in "Lab1Subscriber" Click "Edit Filter" again and select the "Organizational Unit" class to add the "Object Class" attribute to it.

Figure 55: Adding Object Class to Subscriber filter.

13. Click "Apply" and then "Close" to commit your change.
    
    
14. Configure the Lab1 driver for "Manual" start. Right-click MyDriverSet->Properties and select the DirXML tab, then choose "Drivers" in the menu.
    
    

Figure 56: Configuring lab driver for manual startup.

14. Select the "Properties" button which will bring up the Lab1Driver Properties page. Under the DirXML tab, select "Driver Configuration" in the menu and click on the "Startup Option" tab.
    
    

Figure 57: Lab driver properties page.

15. Choose "Manual" and apply these changes.
    
    
16. Stop and restart directory services. In Control Panel->NDS Services, shutdown and restart eDirectory.
    
    

Figure 58: Stopping and restarting eDirectory.

16. Start DSTrace. From NDS Services in the Control Panel, start DSTrace. If DSTrace has not been set up, do the following: Right-click MyDriverSet->Properties, Other tab, and set DirXML-DriverTraceLevel to 4 (you may need to add the attribute to do this click add and browse for it), then start it.
    
    

Figure 59: Starting DSTrace.

1. Edit DSTrace. Make sure you have DirXML and DirXML Drivers checked. Checking additional boxes will only complicate the DSTrace output on you workstation.
   
   

Figure 60: Editing DSTrace.

17. On DSTrace screen, select Edit->Options from the menu, then click Clear All button and select the DirXML items. Click OK.
    
    
18. Start the Lab1Driver. Right-click MyDriverSet->Properties "Drivers" menu, select the Lab1Driver and choose the "Start" button.
    
    

Figure 61: PBX driver interface screen.

1. The PBX interface screen should pop up on your workstation screen. If you do not get the screen, then look at the DSTrace screen.
   
   

   Note:

   The output of DSTrace is color coded. Green indicates that the displayed component is operating correctly. Red indicates that there is a problem with the component. This will give you direction as to where to look in the PDX driver to solve the problem. Don't worry about the other colors for this course.
   
   

Figure 62: Usage of PBX Simulator.

19. Create new users accounts and see them sychronized in eDirectory.
    
    

PBXSimulator Notes

• Always remember to double-click list items in the PBXSimiluator application to select them as shown in figure above.
  
  
• User modifications are not supported.
  
  
• The lab driver will poll PBXSimulator every 4 seconds and print a trace similar to the following in the DSTrace window: PBXAccountPanel.getDBEvents()
  
  
• The following steps will have you create objects on the PBXSimulator side or the eDirectory side and have corresponding objects created on the other side by the lab driver.
  
  
• When accounts are created on the PBXSimulator side, you must select "Refresh" on ConsoleOnes's "View" menu to have ConsoleOne's display updated so that you can see the new object.
  
  
• If you copy a .JAR file into c:\Novell\NDS\Lib, you must shut down eDirectory and restart in order to have the change take effect.
  
  
• Use DSTrace to help you troubleshoot. Create a new trace for each operation so that you won't get confused when reading output.
  
  

Important: $DATA;

The driver must be funtioning before continuing.

1. Modify the driver parameters. Add new directory path location configuration parameters to the LabDriver DirXML driver. Open the file, "C:\DirXMLCrsFldr\Lab1Driver\sources\rules\drvrCfg.xml" in Notepad.
   
   
2. Change the location of the PBX database to the installation location, e.g. c:\DirXMLCrsFldr\pbx\ and change the tree name as well if needed. Save and copy all of the information in the file.
   
   
3. Right-click Lab1Driver->Properties, select the Driver "Configuration" from the DirXML tab. Select the Driver Parameters XML tab and paste in the drvrcfg.xml code.
   
   

Figure 63: PBX driver configuration screen.

4. Apply the changes. After applying the changes, they should be seen and can be edited from the Driver Parameters tab.
   
   

   Note:

   The XML from the "drvrCfg.xml" file that you copied into the Lab1Driver object was parsed by the DirXML snapin when you committed the change. The values specified by the XML are now editable by the administrator in the Driver Parameters panel. When the driver is started, the DirXML engine will read these parameter values and send them to the driver shim's init( ) method as an XML document input parameter.
   
   

In the first two labs, the location of the "pbx" directory accessed by the driver shim is hard-coded into the shim itself, requiring a recompilation of this executable if the directory is ever moved. To make the driver more configurable, in this lab we will add code to the driver shim so that it can parse input parameters to obtain administrator entered directory paths and other information.

5. Edit the Lab1Driver.java file. Search the java file for "WRITE CODE HERE" in the LAB 3 section of the file. Copy the following into the java file.
   
   

Element pathElement =
   (Element)doc.getElementsByTagName("pbxDBFilePath").item(0);
if (pathElement != null)
{ 
   
   Node textNode = pathElement.getFirstChild();
   if ( textNode != null)
   { 
   
      int type = textNode.getNodeType();
      if( type == Node.TEXT_NODE )
      { 
   
         String textValue = textNode.getNodeValue();
         if(textValue !=null)
         { 
   
            pbxDBFilePath = textValue.trim(); // to get rid of white space
            System.out.println( "pbxDBFilePath = "+ pbxDBFilePath ); 
   
         } 
   
      } 
   
   } 
   
}

6. Also, set pbxDBFilePath and pbxNDSPath to "null" where defined at the top of the code, as shown:
   
   

   String pbxDBFilePath=null; 
   String pbxNDSPath = null;

7. Rebuild the driver and copy it to the c:\Novell\NDS\lib directory.
   
   
8. Run and test your driver.