1.3 DirXML Architecture

In the DirXML framework, eDirectory is the hub. Other applications and directories publish their changes to eDirectory, and eDirectory sends changes to the applications and directories that have subscribed for them. Thus there are two main flows of data, as discussed in the driver introduction:

The DirXML engine and the DirXML drivers are the key components that implement the publisher and subscriber channels and thus connect eDirectory with the other application.

All data is exchanged in XML (eXtensible Mark-up Language) documents. The DirXML engine translates an eDirectory event into an XML document and uses rules to determine how the modification is sent to the application. The engine uses the following types of rules and style sheets:

The figure below illustrates this architecture and shows that the DirXML engine does most of the work.

Figure 1-1 DirXML Architecture

The DirXML driver is designed to be a data pipe. It has the following responsibilities for the subscriber channel:

The DirXML driver has the following responsibilities for the publisher channel:

A DirXML driver does not need to understand rules and style sheets because the driver has no responsibility for rule processing. The DirXML engine is responsible for all rule and style sheet processing.

1.3.1 DirXML Features

The flexibility and simplicity of DirXML come from the following features.

XML. All eDirectory data and events are exchanged between eDirectory and the application in the format of XML (eXtensible Markup Language) documents. The use of this popular standard allows any XML-aware application to easily consume this data. XML is a subset of SGML (Standard Generalized Markup Language) and more flexible than HTML (Hyper Text Markup Language) because XML allows tags to be defined by the developer. Novell has used XML to define tags for such items as objects, attributes, and values. These definitions can be found in the nds.dtd file. This particular definition of XML tags is referred to as XDS.

Associations. DirXML does not need to share a unique ID with the other application. It uses an association attribute which links an eDirectory entry to an entry in the external application. The attribute is multivalued, so that each DirXML driver that is synchronizing data with eDirectory can add its own association. What is placed in the attribute is dependent upon the application. For example, if the application uses a record number to uniquely identify an entry, the record number is put in the association attribute. If the application uses a distinguished name, that is used in the attribute.

Schema Mapping. eDirectory and the other applications will have different schema names for the same data. A mapping rule per driver allows you to map any eDirectory attribute or class to any application attribute or class. For example, the eDirectory Surname attribute can be mapped to the Last Name attribute in one application and to the Family Name field in another application.

Authoritative Data Sources. eDirectory rights and DirXML filters determine which application has sufficient rights to update an attribute or an entry. For example, if you synchronize with a PBX application, you can make the PBX DirXML driver the authoritative data source for telephone number attributes. Other applications with DirXML drivers can obtain updates to these attributes but they cannot change them in eDirectory.

Create Rules. Each application that is being synchronized with eDirectory might have different conditions for creating a new entry. The create rules can be configured to list those conditions, and the DirXML engine will ensure that the entry has values for all the required attributes before it is created.

For example, eDirectory requires a name, a surname, and an object class to create a User. If the PBX application requires a first name, surname, telephone number, and location, DirXML ensures the entry has values for these attributes before it sends a create command to the PBX application.

Selected Data. Most applications store information that is specific to the application. The DirXML architecture allows the administrator to select only the data that is relevant for sharing: the eDirectory attributes and classes that correspond to relevant application-specific records and fields.

For example, an HR database would want to share user-type objects with eDirectory, but would not be interested in network resource objects such as servers, printers, and volumes. eDirectory would want to share a user's given name, surname, initials, telephone numbers, and work location, but would probably not be interested in storing the user's family information and employment history (unless another eDirectory application needs access to this information). If eDirectory does not currently have classes or attributes for the shared data, the eDirectory schema can be extended to include them. In this example, eDirectory becomes the repository of information that eDirectory needs and which other applications can use. The application remains the repository for the information that is required only by the application.

Data Transformations. DirXML uses the Extensible Stylesheet Language Transformation (XSLT) as a mechanism for data transformation. For example, if one external application stores date information in a day-month-year format, an XSL transformation rule can ensure that date information that is stored in a month-day-year format is converted before sending it to the external application. XSL is an extensible language that allows driver developers and system administrators to supply plug-ins for data transformations not covered in the basic language.

DirXML Engine. The DirXML engine is responsible for eDirectory communication, schema mapping, rule enforcement, and data filtering. Since the engine does most of the work, the DirXML driver, in comparison, is relatively simple and direct.

1.3.2 DirXML Engine and Driver Interaction

The DirXML engine is the key module in the DirXML architecture and provides the interface that allows DirXML drivers to synchronize external application information with eDirectory. The DirXML engine is the module that communicates directly with eDirectory and converts the eDirectory data into XML format.

This section covers the following topics:

The following graphic illustrates the interactions among the DirXML engine, eDirectory, a DirXML driver, and an external application.

Figure 1-2 DirXML Interactions

When eDirectory initializes, it reads the event filter, registers the driver for the appropriate eDirectory events, filters the data according to the filter's specification, and sets up a cache for the events. eDirectory then notifies the DirXML engine when an event occurs. eDirectory events are local to the server; they are not global to the eDirectory tree. Therefore, the DirXML engine receives only the modifications from local replicas. If user data is modified on a partition that does not reside on the local server, DirXML is not notified of the modifications. The eDirectory server with the DirXML engine must be configured to contain replicas of all the objects that are being synchronized with the external application.

eDirectory 8.5 adds a new type of replica for filtering data. Filtered replicas allow you to select which object types (for example, Users) and which attributes (for example Surname, Given Name, CN, and Telephone Number) a replica contains. Other object types such as Printers and Servers and User attributes such as Title or Manager are not included in the filtered replica. With eDirectory 8.5, the server running DirXML can be set up with replicas that include the data specified in the DirXML filter and rules.

When the DirXML engine receives the eDirectory events, it reads the rules you have set up for the subscriber (event transformations, matching, placement, create, mapping, and output transformations) and sends the data to your subscriber channel.

The subscriber channel of the DirXML driver receives the XML data from the DirXML engine, converts it to the application's APIs, and sends it to the external application.

The publisher channel of the DirXML driver checks for events in the external application, converts the events into XML, and sends the XML to the DirXML engine. The engine applies the rules, changes the XML to eDirectory commands, and sends them to eDirectory.

Subscriber Channel

The subscriber portion of your driver sends changes from eDirectory to your application. It is the object that implements the SubscriptionShim interface and is responsible for the following tasks:

  • Data Conversion. Your driver needs to convert the XML data to a format that the external application can use. This tool kit includes the nds.dtd file which contains the XML definitions for the input and output commands and for the rules (matching, creation, placement, and mapping). You can also use an output transformation style sheet to help in the conversion. If possible, all data conversion should be handled in rules and style sheets because these can be modified to match a particular installation of the external application. If the driver handles the data conversion, modifications to the process require recompiling the driver.

  • Data Sending. The driver needs to use the interface of the external application to send the data to the application. The driver should not return to the DirXML engine until the application returns a response or a reasonable timeout expires.

  • Response Handling. The driver needs to convert the response from the application into an XDS document and return it to the DirXML engine.

The DirXML engine is responsible for filtering the eDirectory data, converting it to XML, and applying the event transformations, rules, and output transformations. Event transformations can be used to change an XDS command (such as modify) to another XDS command (such as add). As a driver developer, you can also use an event transformation to change an XDS command into a non-XDS command understood by your application. The DirXML engine does not apply matching and create rules to non-XDS commands but sends them to the schema mapping rules and then to your driver.

Publisher Channel

The publisher portion of the driver performs the gathering and sending of updates from the external application to eDirectory. It is the object that implements the PublicationShim interface. The following tasks are driver-implementation specific.

  • Changes. Your driver needs to be informed of changes to the information in the external application.

  • Filtering. Once your driver has gathered the changed information, it should filter it to the correct set of data so that only data being shared is sent to eDirectory. If your driver doesn't filter the data, eDirectory will filter and discard the data that doesn't apply. However, system resources are used more efficiently when the driver filters the data.

  • Converting. Your driver needs to convert the data from the application's commands to XDS format and then send the data to the DirXML engine. If the application uses XML, you can use input transformations to change from the application's XML to XDS.

  • Sending. Your driver sends the data to the DirXML engine and receives an XML response document.

Once the data is sent to the DirXML engine, the DirXML engine is responsible for applying the rules and sending it to eDirectory. The event transform rules can be used to transform one XDS command into another. They can also convert an external application event into an XDS command. However, if the event is transformed to a format other than XDS, the DirXML engine drops it (the black hole in the figure) and returns an error.

eDirectory responds to the DirXML engine which converts the response to an XML document. The mapping rules, style sheets, and your driver convert the response to a format that you can send to the external application as completion codes, if necessary.

1.3.3 Driver Interaction with eDirectory Objects and Attributes

The DirXML driver has two main entities with which it communicates: the DirXML engine and the external application. However, the driver is affected by information stored in a number of eDirectory objects. The DirXML engine interacts with these eDirectory objects. It knows which objects belong to your driver and uses the object information to modify the XDS formatted document that is sent to your driver. For a definition of the DirXML classes and attributes, see Section B.0, DirXML Definitions for the Schema.

The following DirXML attributes and objects are used to modify the document's contents.

  • Filter Attribute for the Subscriber. The DirXML engine registers your driver for a standard set of eDirectory events: create object, delete object, rename object, add attribute value, delete attribute value, and move object. The eDirectory server reads the subscriber filter to restrict the data to the object classes and attributes specified in the filter. For example, if the configuration is intended to synchronize only user information, the filter would specify User objects and modification to other eDirectory objects would be ignored. From the possible User class attributes, the filter would specify selected attributes, such as CN, Given Name, Surname, and Telephone Number. Modifications to other user class attributes would be ignored.

    Although your driver never reads the subscriber filter or interacts directly with it, the contents of the filter affects your driver because the filter determines what data is sent from eDirectory to your driver.

    The subscriber filter is a DirXML-DriverFilter attribute of DirXML-Subscriber objects.

  • Filter Attribute for the Publisher. The DirXML engine uses the publisher filter to ensure that the data it receives from the external application matches the data types specified in the filter. This filter is passed as part of the initialization data so that the driver can filter the events coming from the application to match the data defined in the filter.

    The publisher filter is a DirXML-DriverFilter attribute of DirXML-Publisher objects.

  • Association Attribute. This attribute is an optional attribute for every object in the eDirectory tree. It associates an eDirectory entry with an entry in the external application. Well-designed matching rules automate the creation of associations between existing entries in eDirectory and the application. On add operations, the DirXML driver returns an association as part of an add command and includes an association as part of an add event.

  • Matching Rule Object. Matching rules determine how objects in eDirectory are associated with records in the external application when an association has not already been established. The administrator sets these up, and they determine which attributes and values must match with which fields and values in the external application. For example, the eDirectory administrator can set the rule up so that a User's Surname, Given Name, and Telephone Number attributes must match a Record's Last Name, First Name, and Phone fields before the DirXML engine can automatically create an association.

  • Create Rule Object. Create rules specify what information eDirectory or the application must have before creating a new object or entry. In the rule, the administrator specifies the attributes that must have values, for example, last name, first name, phone number, and login name. This rule can be the same for both the subscriber and the publisher or different. In other words, one application can require more information than the other for creation to succeed.

  • Placement Rule Object. Placement rules determine where new objects are placed in the application. Each driver typically requires at least two placement rules. The publisher needs to know where to created new eDirectory objects when the external application creates a new object, and the subscriber needs to know where to create an external application object when a new object is created in eDirectory. You can have multiple rules. Since eDirectory is hierarchical, multiple rules are useful because they allow you to create objects in multiple containers.

  • Mapping Rule Object. Mapping rules determine how eDirectory class and attribute names are mapped to application's class and attribute names. For example:

    User class

    with

    Client class

    Given Name attribute

    with

    First Name attribute

    Surname attribute

    with

    Last Name attribute

    Initials attribute

    with

    Middle Initial attribute

  • Configuration Attribute. The DirXML-ShimConfigInfo attribute is an XML file that contains any configuration options which a network administrator needs to set for the driver, the subscriber, and the publisher. They are optional, but if you select to use them, your driver initialization code needs to parse the commands that are sent in an XDS init document.

  • Style Sheet Objects. Style sheets are for event, input, and output transformations and may be used for any of the other rules.

For more information on the eDirectory objects and attributes, see Section B.0, DirXML Definitions for the Schema.

For more information about the rules, filters, and style sheets, see Introduction to the Rules and Filters.