DirXML is designed to synchronize information between data sources. The core piece of DirXML, the DirXML engine, handles all synchronization to and from eDirectory, which acts as the hub of the synchronization.
For each application that wishes to synchronize with eDirectory, a driver must be written to do two basic things: Notify the DirXML engine of a change in the application, and receive notifications of changes in eDirectory from the DirXML engine and make those changes in the application.
In order to communicate with any number of applications, an XML format, called XDS, is used as the common denominator. XDS is eDirectory-flavored XML with elements to represent directory objects and the operations you might perform on them.
All information exchanged between your driver and the DirXML engine is in this format. XDS documents contain either a command or event, depending on the flow of information.
Commands are XDS documents received from the DirXML engine, containing changes from eDirectory. Events are XDS documents sent to the DirXML engine, containing changes in your application. This distinction is simple but important, because different actions are required depending whether you are handling a command or an event.
From the standpoint of driver development, the goal is straightforward: for each event that occurs in your application, pass the DirXML engine an XDS document that explains the event. For each command received from the DirXML engine as an XDS document, translate the document into API calls to apply the change.
As previously mentioned, your driver must be able to publish changes to the DirXML engine, and receive changes from the DirXML engine. DirXML defines these actions as publishing and subscribing, named from the point of view of the application. Your application submits changes on the Publisher Channel and receives changes on the Subscriber channel.
Your driver must implement a separate process for each channel.
For example, a user is added in eDirectory. This change could have occurred directly in eDirectory, or in a human resources system that is synchronized to eDirectory using a PeopleSoft or some other dirXML driver. When this change occurs, the DirXML engine sends an XDS document to your driver on the subscriber channel containing information about the change. It might look similar to the following:
<nds dtdversion="2.0" ndsversion="8.7.3">
<source>
<product version="2.0">DirXML</product>
<contact>Novell, Inc.</contact>
</source>
<input>
<add class-name="User" event-id="0" src-dn="\ACME\Sales\Smith"
src-entry-id="33071">
<add-attr attr-name="Surname">
<value timestamp="1040071990#3" type="string">Smith</value>
</add-attr>
<add-attr attr-name="Telephone Number">
<value timestamp="1040072034#1" type="teleNumber">111-1111
</value>
</add-attr>
</add>
</input>
</nds>
Your driver now has an XML document containing a change that occurred in eDirectory.
Your driver shim parses this xml document to determine what actions need to occur to bring the application up to date, and then translates this into API calls.
For an LDAP application, the API calls might look similar to the following:
LDAPAttributeSet attributeSet = new LDAPAttributeSet();
String containerName = "ou=Sales,o=Acme";
attributeSet.add( new LDAPAttribute("objectclass", new String("User")));
attributeSet.add( new LDAPAttribute("sn", new String("Smith")));
attributeSet.add( new LDAPAttribute("telephonenumber",
new String("111-1111")));
String dn = "cn=Smith," + containerName; LDAPEntry newEntry = new LDAPEntry( dn, attributeSet );
It is important to be aware that decisions about where to place new objects, how to create new objects, filling in missing mandatory attributes, and so on, are made in the dirXML engine, not in your driver. Your driver simply needs to report each event that occurs to the dirXML engine, and make any changes requested by the dirXML engine.
A Change to a user's manager occurs in your application, which for this example, is an HR database designed to handle your organization hierarchy. When this change occurs, your driver needs to first find out about the change, then translate the change into an XDS document to send it to the DirXML engine.
Traditionally, the most difficult aspect of authoring a DirXML driver is finding a reliable, consistent source to monitor changes in your application. Some applications, such as eDirectory, have full-featured event notification systems that can simplify this process. Some applications log all changes to a file or other database (which unfortunately can change from release to release), and others have no method of logging changes, which require driver writers to implement their own system. Most vendors consider data sharing a positive feature and are willing to help you determine a suitable method to monitor changes.
For this example, let's say your application has a change monitoring API or persistent search functionality, which asynchronously sends you the events you wish to monitor through a getResponse method when they occur:
//connect, authenticate, and enter the event monitor or persistent search API
while (( event = queue.getResponse()) != null )
//set up conditional statements to determine the type of change
if (event instanceof SomeTypeOfEvent)
{
//transform this event into an XDS document with relevant information
//and send it to the DirXML engine, or call another API to...
}
if (event instanceof SomeOtherTypeOfEvent)
{
//transform this event into an XDS document with relevant information
//and send it to the DirXML engine, or call another API to...
}
...
The implementation of finding and reporting changes is left to your creativity, the only requirement is that in the end, an XDS document is sent to the DirXML engine containing the change.
If you have any exposure to DirXML, you have likely heard much talk about policies, stylesheets, transformations, and many other things that can cloud your idea of what exactly your driver must do.
Simply put, policies modify an event sent to the DirXML engine to make it work for an individual environment. For example, one organization might use the inetorgperson as the main user class, while another organization might use User. If you are synchronizing a phone number, you don't really care what object class is used, but you can't write code to handle every situation. Therefore, a policy can be implemented to add the phone number change to an inetorgperson for the first organization, and a separate rule can be implemented to make it work for the User class.
Policies make schema transformations, specify matching criteria to determine if an object already exists in an application or eDirectory, and many other things. Because of this, an add event reported by your application may end out as a modify operation in eDirectory, if a matching policy determines that the object you added already exists in the data store.
Most of the time, your driver does not need to make many decisions about the events it reports. If you think that somebody might want to synchronize an event using your driver, you should probably report it. There are exceptions, however, in the case that your driver has to transfer a lot of data over the wire, you might want to limit the events you report, and you will probably think of others as you learn your application. This decision of which events to report is left entirely up to you, just be aware that it is often easier from an implementation standpoint to filter events in the engine than it is to re-write or re-compile your driver to handle a new situation.
On the subscription channel, it is basically the same in reverse. If an event is sent to your application, it should be logged. For example, a new user is created in eDirectory. Before sending this command to your driver, the DirXML engine calls a series of policies, one of which defines the way objects are created, in which rules can determine if a corresponding user already exists in your application, make decisions about placement, provide default values for required attributes that are not specified, and so on. This add event may be transformed into a modify event if the object exists in your application, and attributes that were not contained in the original event could be added to conform with the object creation model of your application.
Once these rules are applied and a command is sent to your driver, your driver should make the change in the application. If the change is somehow incorrect, then logic needs to be added to the creation policy, not to your driver.
Once again, the goal is straightforward: for each event that occurs in your application, pass the DirXML engine an XDS document that explains the event. For each command received from the DirXML engine as an XDS document, translate the command into API calls and execute the command.
To learn more about policies, see the Policy Builder and Driver Customization Guide.
From the introduction, you are probably aware that a good portion of your development time is spent parsing and creating XDS documents. To work with XDS documents, there are four APIs available:
The two most common XML parsing interfaces in use today are DOM and SAX.
DOM builds an XML document into a tree structure, you navigate this tree to find information. SAX is an event-driven approach that reports events using callbacks.
DOM and SAX are both open interfaces that can handle any sort of XML document. With this flexibility there is increased development overhead, because every type of XML document no is handled in a similar fashion.
To reduce development time, Novell has developed a custom XML parsing API, called XDS Libraries, which extends the DOM interface. The XDS Libraries are designed to work specifically with DirXML and eDirectory, enabling them to relieve a fairly large portion of the development overhead involved parsing XML documents.
The XDS Libraries provide a framework for each channel that calls a method you supply whenever a certain event is received. For example, when you driver receives an add event, the XDS Libraries determine the event type for you and call the method you have selected to handle add events. Methods are also supplied to create XDS documents using API calls, relieving you from creating the XDS documents yourself, and documents are validated to reduce the chance of encountering an error.
Each interface is better for different situations, and there are extensive guides to each of the open interfaces on the Web. XDS is simplified and can reduce development time, but it works only with the NDS DTD and cannot be used when processing other types of XML documents. Serial processing is usually avoided if another interface can be used.
These interfaces are discussed in further detail in Section 2.2, Getting Started.
Typically, this is the most difficult part of creating a custom driver, and unfortunately, it is the part where we can only provide general guidelines. To monitor changes, you first need to determine how the application stores data, what interfaces are exposed in what programming languages, if the application logs data or supplies an event system, and so on.
If you are lucky, your application stores information in XML and has a full-featured event system. In this case you would simply transform the application's XML into XDS whenever an event occurs and pass this to the DirXML engine.
In some circumstances, the application might not have even a suitable event log, so you might need to build your own event log, implement a system to read this log, then transform the stored events into XDS in order to make the synchronization work.
As mentioned previously, this is left to your creativity.
If you are new to DirXML driver development, Novell DeveloperNet® University provides a free, online DirXML driver creation training course, that is highly recommended. The course is designed to take approximately 24 hours to complete and walks you through the creation of a custom DirXML PBX driver.
DeveloperNet University: Custom Driver Development Course
Section 2.0, Writing a DirXML Driver discusses modifying the provided skeleton drivers to create your DirXML driver.