Novell DirXML ™ Commands, Events, and Transformations Shon Vella Software Engineer, Consultant Novell, Inc. Perin Blanchard Software Engineer, Consultant Novell, Inc.

DirXML ™ and XML DirXML is a flexible data sharing service  Shares data between disparate systems throughout the network  Flexibility is achieved by encoding the shared data in XML and using configurable rules to transform the data as it is transferred between systems  In order to use DirXML effectively to implement complex business processes it is necessary to understand DirXML’s XML vocabulary and the ways that the XML can be transformed by rules

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

DirXML and XSLT XSLT is a transformation language for XML  XSLT is an acronym for eXtensible Stylesheet Language Transformations  XSLT 1.0 is a World Wide Web Consortium (W3C) recommendation published in 1999  XSLT is a vocabulary of XML that specifies transformation semantics that operate on XML documents  DirXML uses XSLT 1.0 as a method of implementing rules

John Doe An Introductory Stylesheet Convert an XML documentFor display in HTML as First name: John Last name: Doe Phone:

An Introductory Stylesheet: Stylesheet Element First name: Last name: Phone:

An Introductory Stylesheet: Namespace and Instructions First name: Last name: Phone:

An Introductory Stylesheet: Templates and Match Patterns First name: Last name: Phone:

An Introductory Stylesheet: Recursion and XPath Expressions First name: Last name: Phone:

An Introductory Stylesheet: Literal Result Elements and Text First name: Last name: Phone:

DirXML Architecture Novell eDirectory™DirXML Application API Event caching DirXML engine DirXML application shim eDirectory server

NDS.DTD NDS.DTD defines document structure for  Commands and events in the DirXML Engine (XDS)  The simple form of the following DirXML rules Schema mapping rules Matching rules Create rules Placement rules The NDS.DTD file, together with documentation on semantics and usage, is available in the NDK 

DirXML’s XML Vocabulary DirXML defines an XML vocabulary that DirXML uses to encode data events and commands  The vocabulary is called XDS  XDS documents are used as the medium of communication between the DirXML engine and a DirXML application shim  Used internally by the DirXML engine  Operated on by DirXML rules  XDS is user-extensible and is not validated against the DTD by the DirXML engine

Input and Output Documents An XDS document consists of an element with an optional element and a single or element  Documents used to report data events from eDirectory or from an application are input documents  Documents used to command eDirectory or an application to perform an action are input documents  Documents returned in response to an input document are output documents

DirXML Novell, Inc. <add class-name="User" src-dn="Users\Julia" dest-dn="cn=Julia,o=Users" event-id="0"> Gulia Input Example An application shim is sent the following document as input

JuliaGulia1 Output Example The application shim might respond with

Events vs. Commands An event is a report of a data change event in either Novell eDirectory or an application A command is an instruction to either eDirectory or an application When an event notification is sent to DirXML the DirXML engine will determine, based on the rules, what commands need to be issued to keep the data synchronized

Input Events and Commands Events and commands that may be children of an element include   Other allowed children of are less frequently used

Input Events and Commands The,,,, and elements represent both commands and events  Commands and events have essentially the same syntax  Interpretation depends on context Events are sent to the DirXML engine by the application shim and by eDirectory Commands are sent to the application shim and to eDirectory by DirXML

Output Responses Events and commands that can be children of an element include   Other allowed children of are less frequently used

Common Attributes Attributes common to many events and commands and responses include  class-name The base class of the object  dest-dn The DN of the target object for commands  src-dn The DN of the source object for events  event-id An identifier used to tag the results of an event or command

Common Content Elements Content elements that are common to many events, commands, and responses include 

Association The value of the element is a unique key provided by the application shim used to identify the source application object of an event or the target application object of a command  The key is used to associate objects in eDirectory with an object in another application and is stored as an attribute of the eDirectory object  The state attribute is used internally by DirXML for control purposes

Value elements are used to represent object values or properties  The type attribute is used to determine how to interpret the content “Octet” values contain base64-encoded binary data “Structured” values consist of zero or more elements All other value types use a simple string representation of the value  The association-ref attribute is used in conjunction with referential attributes

Values Examples Example elements Fred RM8FFyP21kirzwqLjr+Q6g== [All Attributes Rights] \TREE\O\Admin 2

Status A element is used to return the status of processing a command or event  More than one element can be returned as a result of a given event or command  The level attribute indicates the disposition of the associated event or command Possible values “success”, “warning”, “error”, “retry”, and “fatal”  The event-id attribute—the event-ID value of the corresponding event or command element  The content is a specific error or warning message

Operation vetoed by Placement Rule ERR_NO_ACCESS Status Examples Example elements

Add An element is used  As an event from an application shim or from eDirectory notifying DirXML that an object was added  As a command from DirXML instructing an application shim to add an object in the application or instructing eDirectory to add an object

Add Example A simple object-creation event from a hypothetical application JDoe2474 John Doe

Modify A element is used  As an event from an application shim or from eDirectory notifying DirXML that one or more of an object’s attribute values were modified  As a command from DirXML instructing an application shim to modify attribute values in an application object or instructing eDirectory to modify attribute values in an eDirectory object

Modify Example A simple object-modification event from a hypothetical application JDoe

Rename A element is used  As an event from an application shim or from eDirectory notifying DirXML that an object was renamed  As a command from DirXML instructing an application shim to rename an application object or from DirXML instructing eDirectory to rename an eDirectory object

Rename Example A simple object-rename event from a hypothetical application <rename class-name="User" src-dn="cn=JDoe,o=novell" old-src-dn="cn=John Doe,o=novell"> JDoe2474 JDoe

Move A element is used  As an event from an application shim or from eDirectory notifying DirXML that an object was moved  As a command from DirXML instructing an application shim to move an application object or from DirXML instructing eDirectory to move an eDirectory object

Move Example A simple object-move event from a hypothetical application <move class-name="User" src-dn="cn=JDoe,o=Inactive" old-src-dn="cn=JDoe,o=novell"> JDoe2474 TC

Query A element is used as a command instructing an application shim or eDirectory to find and/or read objects and their attributes Queries are limited by specification of  A base object  Scope Entry, subordinates, or subtree  Classes to include  Attribute values to search for  Attributes to return in the response

Query (cont.) A query that reads attributes values from an object JDoe2474

Query (cont.) A query that searches for objects of a particular class with particular attribute values John

Query Response Zero or more elements are contained in the response to a query

Query Response Example A potential response to a query that reads an attribute value from an object JDoe

Delete A element is used  As an event from an application shim or from eDirectory notifying DirXML that an object was deleted  As a command from DirXML instructing an application shim or instructing eDirectory to delete an object

Delete (cont.) A simple object-delete event from a hypothetical application JDoe2474

Submitting samples to DirXML  demonstratio

Rules: XML Transformations Rules control how the DirXML engine transforms an event reported on a channel input into set of commands for the channel output  Subscriber Input event comes from eDirectory and the output command(s) are sent to the application shim  Publisher Input event comes from the application shim and the output command(s) are sent to eDirectory  Any DirXML rule can be implemented as an XSLT stylesheet

Simple Rules Four types of rules perform a well-defined role and have a simple XML vocabulary to describe the event-to-command transformation  Schema Mapping rules  Matching rules  Create rules  Placement rules Any of the above rule types can also be implemented using an XSLT stylesheet

XSLT-Only Rules Four types of rules allow for more general customization and must be implemented with an XSLT stylesheet  Event Transformation Rules  Command Transformation Rules  Input Transformation Rules  Output Transformation Rules

Rule Chaining Any rule can be implemented as a series of individual rule objects chained together The output of each rule object is passed as the input to the next rule object in the chain Used to supplement the behavior of a simple rule with a stylesheet without having to implement all the rule logic in a stylesheet

Schema Mapping Rules Schema Mapping Rules are used to map class names and attribute names between eDirectory and application namespaces  Maps all class-name attributes in an XDS document  Maps all attr-name attributes in an XDS document attr-name mapping may be based on the class-name that is in scope  Is bi-directional and same rule operates on both channels

Simple Schema Mapping Rules Simple Schema Mapping Rules provide a 1-1 mapping of schema names Attribute name mappings may be optionally dependent on the class name Any other more complex mapping must be done with an XSLT stylesheet

User inetOrgPerson Given Name givenName Surname sn Simple Schema Mapping Rules Example Schema Mapping Rules for a hypothetical application

Simple Schema Mapping Rules Transformation Example <add class-name="User" src-dn="\TREE\Provo\JSmith"> John Smith Smith John To application shim <add class-name="inetOrgPerson" src-dn="\TREE\Provo\JSmith"> John Smith Smith John From eDirectory

XSLT Schema Mapping Rules Example <xsl:transform xmlns:xsl=" version="1.0"> <xsl:template mode="fromNds"> inetOrgPerson User <xsl:template Name' and mode="fromNds"> givenName <xsl:template and mode="toNds"> Given Name sn Surname

Matching Rules Matching Rules are used to try to find a matching object in the channel destination for an unassociated object in the channel source as a result of an event from the channel source  Applied before deciding if a new object should be created in the channel destination  On Publisher channel adds a dest-dn attribute for matches  On Subscriber channel adds an attribute for matches

Simple Matching Rules An applicable rule is selected by object class and available attributes from the A subtree-scoped query for the channel destination is generated based on the attribute values and class name from the and the base object specified by the rule Each applicable rule is tried until a match is found

Simple Matching Rule Example Matching Rules for Subscriber Channel of hypothetical application

Simple Matching Rules Transformation Example (Subscriber) <add class-name="User" src-dn="\TREE\Provo\JSmith"> John Smith Smith John After <add class-name="User" src-dn="\TREE\Provo\JSmith"> JSmith99 John Smith Smith John Before

Simple Matching Rules Transformation Example (Publisher) <add class-name="User" src-dn="cn=Jsmith,o=novell" JSmith99 John Smith Smith John After <add class-name="User" src-dn="cn=Jsmith,o=novell" dest-dn="\TREE\Provo\Jsmith"> JSmith99 John Smith Smith John Before

XSLT Matching Rules Example \ \MY-TREE\ <xsl:variable name="result" select="query:query($destQueryProcessor,$query)"/> <xsl:if =

Create Rules Create Rules determine if it is permissible to generate an command as a result of an event  Veto disallowed elements by removing them from the document  Fill in default values for unspecified attributes  Add initial passwords  Specify a template object  Only applied after any Matching Rules determine that there are no matching objects

Simple Create Rules An applicable rule is selected by object class and matching attributes from the The is vetoed if any of the required attributes are missing and no default is specified A template-dn attribute is added to an allowed if specified by the rule Only the first applicable rule is applied If no applicable rule is found the is allowed

Simple Create Rules Example Defense <required-attr attr-name="Given Name"/> <required-attr attr-name="Surname"/> <required-attr attr-name="Clearance"/> <template template-dn="tmplt\Secure"/> <required-attr attr-name="Given Name"/> <required-attr attr-name="Surname"/> <required-attr attr-name="Clearance"> None Create Rules for Publisher Channel of hypothetical application

Simple Create Rules Transformation Example <add class-name="User" src-dn="\TREE\Provo\JSmith" JSmith99 Smith John After <add class-name="User" src-dn="\TREE\Provo\JSmith"> JSmith99 Smith John None Before

XSLT Create Rules Example <xsl:transform xmlns:xsl=" version="1.0"> <xsl:if and Name'] and tmplt\Secure <xsl:if and Name']"> None

Placement Rules Placement Rules are used to give an object that is about to be created a name and location  Adds a dest-dn attribute value to the  Only applied after any Create Rules determine that the add operation is allowed  Always required on the Publisher channel for object creation  Might not be required on the Subscriber channel depending on the application shim and application

Simple Placement Rules An applicable rule is selected by object class, matching attributes, and matching src-dn from the A destination dn is generated by concatenation of literal text and pieces of the src-dn or attribute values from the The pieces of the src-dn used may be converted to a different format (slash/dot/ldap/custom)

Simple Placement Rules Example Matching Rules for Subscriber Channel of hypothetical application,o=novell cn=,ou=,o=novell

Simple Placement Rules Transformation Example <add class-name="User" src-dn="\TREE\Provo\JSmith"> Smith John Eng After <add class-name="User" src-dn="\TREE\Provo\JSmith" dest-dn="cn=Jsmith,ou=Eng,o=novell"> Smith John Eng Before

XSLT Placement Rules Example <xsl:transform xmlns:xsl=" version="1.0"> <xsl:variable name="location" <xsl:variable name="rdn" select="substring-after( ','), '=')"/> \TREE\novell\ Unknown \

Input and Output Transformation Rules Input and Output Transformation Rules are used primarily to convert data formats  Sometimes also used to convert XDS to/from other vocabularies  XDS documents sent or returned to an application shim are sent through the Output Transformation Rules  XDS documents sent from or returned from an application shim to the DirXML engine are sent through the Input Transformation Rules  The same rules operate on both channels  Always implemented as an XSLT Stylesheet

Input and Output Transformation Rules Example Input Transformation Rules From: nnn-nnn-nnnn To: (nnn)nnn-nnnn Output Transformation Rules From: (nnn)nnn-nnnn To:nnn-nnn-nnnn <xsl:transform xmlns:xsl=" version="1.0"> <xsl:template Number']//value/text()"> <xsl:transform xmlns:xsl=" version="1.0"> <xsl:template Number']//value/text()">

Event Transformation Rules Event Transformation Rules are used to perform preliminary transformations on an event  Custom event filtering  Transforming the event directly into a custom command to be passed to the application  Generating additional events  Always implemented as an XSLT Stylesheet

Event Transformation Rules Example Filter out all renames and moves

Command Transformation Rules Command Transformation Rules are used to perform any final transformations on commands before they are sent to eDirectory or the application shim  Changing the command type  Blocking commands  Adding additional commands  Controlling the output of merge processing  Always implemented as an XSLT Stylesheet

Command Transformation Rules Example Convert to set Login Disabled to true true

DirXML Event Processing Event to XML Event Transformation Association Processor Add Event? Schema Mapper Output Transformation Matching Rule Create Rule Placement Rule Matching Rule Create Rule Placement Rule Subscriber Add Processor Publisher Add Processor Add Event? Association Processor Input Transformation Schema Mapper Event Transformation Publisher Filter Subscriber Filter Event Cache XML to NDS no yes no yes The DirXML Engine Command Transformation Command Transformation

demonstratio Rules in action

DirXML Links For the latest information on DirXML and drivers go to For course schedules and registration information go to For boot camp registration information go to

Conclusion Understanding XDS and the transformations that can be performed via Rules will enable you to use DirXML to effectively share data throughout the network