1. www.novell.com Novell DirXML ™ Commands, Events, and Transformations Shon Vella Software Engineer, Consultant Novell, Inc. svella@novell.com Perin Blanchard Software Engineer, Consultant Novell, Inc. pblanchard@novell.com

2. 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

3. 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

5. 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

6. John Doe 801-555-1234 An Introductory Stylesheet Convert an XML documentFor display in HTML as First name: John Last name: Doe Phone: 801-555-1234

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

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

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

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

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

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

13. 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  http://developer.novell.com/ndk/dirxml.htm

14. 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

15. 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

16. 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

17. JuliaGulia1 Output Example The application shim might respond with

18. 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

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

20. 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

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

22. 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

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

24. 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

25. 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

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

27. 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

28. Operation vetoed by Placement Rule ERR_NO_ACCESS Status Examples Example elements

29. 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

30. Add Example A simple object-creation event from a hypothetical application JDoe2474 John Doe 555-2474

31. 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

32. Modify Example A simple object-modification event from a hypothetical application JDoe2474 555-2474 555-1234

33. 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

34. 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

35. 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

36. 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 TC234689887

37. 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

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

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

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

41. Query Response Example A potential response to a query that reads an attribute value from an object JDoe2474 555-2474

42. 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

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

44. Submitting samples to DirXML  demonstratio

45. 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

46. 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

47. 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

48. 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

49. 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

50. 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

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

52. 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

53. XSLT Schema Mapping Rules Example <xsl:transform xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"> <xsl:template match="@class-name[.='User']" mode="fromNds"> inetOrgPerson User <xsl:template match="@attr-name[.='Given Name' and ancestor-or-self::*[@class-name][1]/@class-name[.='User']]" mode="fromNds"> givenName <xsl:template match="@attr-name[.='givenName' and ancestor-or-self::*[@class-name][1]/@class-name[.='inetOrgPerson']]" mode="toNds"> Given Name sn Surname

54. 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

55. 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

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

57. 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

58. 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

59. XSLT Matching Rules Example \ \MY-TREE\ <xsl:variable name="result" select="query:query($destQueryProcessor,$query)"/> <xsl:if test="translate(@class-name,$ucase,$lcase) = translate($instance/@class-name,$ucase,$lcase)">

60. 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

61. 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

62. 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

63. 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

64. XSLT Create Rules Example <xsl:transform xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"> <xsl:if test="add-attr[@attr-name='Surname'] and add-attr[@attr-name='Given Name'] and add-attr[@attr-name='Clearance']"> tmplt\Secure <xsl:if test="add-attr[@attr-name='Surname'] and add-attr[@attr-name='Given Name']"> None

65. 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

66. 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)

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

68. 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

69. XSLT Placement Rules Example <xsl:transform xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"> <xsl:variable name="location" select="string(add-attr[@attr-name='L']/value)"/> <xsl:variable name="rdn" select="substring-after( substring-before(@src-dn, ','), '=')"/> \TREE\novell\ Unknown \

70. 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

71. 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="http://www.w3.org/1999/XSL/Transform" version="1.0"> <xsl:template match="*[@attr-name='Telephone Number']//value/text()"> <xsl:transform xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"> <xsl:template match="*[@attr-name='Telephone Number']//value/text()">

72. 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

73. Event Transformation Rules Example Filter out all renames and moves

74. 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

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

76. 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

77. demonstratio Rules in action

78. DirXML Links For the latest information on DirXML and drivers go to http://www.novell.com/products/nds/dirxml/ For course schedules and registration information go to http://www.novell.com/education For boot camp registration information go to http://www.novell.com/registernow

79. 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