Novell is now a part of Micro Focus

DirXML and the Reporting & Notification Service (RNS)

Articles and Tips: article

Steven L. Weitzeil
Director of Engineering, DirXML
Novell Inc.
sweitzeil@novell.com

01 Aug 2002


This AppNote introduces the Reporting & Notification Service (RNS) included in Novell's DirXML 1.1a product. RNS allows network administrators to be notified, by whatever means are best stuied to their specific environment, in the event of system errors, warnings, retries, and successes.


Topics

DirXML, Reporting & Notification Service (RNS), application integration, directory-enabled applications

Products

DirXML 1.1a

Audience

network administrators

Level

intermediate

Prerequisite Skills

familiarity with database reporting tools

Operating System

n/a

Tools

Crystal Reports

Sample Code

no

Introduction

Large corporations typically use a wide variety of applications, each representing isolated sets of data. It is very likely that a significant amount of data on those applications is duplicated. Every employee's name is likely stored in the Human Resources system, the corporate directory, the e-mail system, the payroll system, and so on. Phone numbers, addresses, and identification numbers are additional examples of potentially duplicated data.

When a new employee is hired, how does that employee's information get entered into each of the corporate applications that need it? Typically, the information is manually entered into each system. This duplication of effort increases the potential for human error and faulty data. Since all of the systems are not updated simultaneously, there are periods of time where the corporate systems are out of synchronization.

Similar problems exist when an employee leaves the company. If an employee is not removed from all applications in a timely manner, it leaves the corporation open to security risk. Former employees can potentially access systems for a time, even though the company no longer employs them.

Administrators of corporate systems tend to be very protective of their environments. This makes it difficult to coordinate data sharing efforts within an enterprise. Getting permission to interface one application with another can be a real challenge. Suppose you hire a programmer to write a new corporate application. How many systems will that engineer need to access to get the required information? How many APIs will the engineer need to deal with to access the information on those systems? Every time a source application changes, the programmer will need to modify this new application.

The Solution: DirXML

Novell's DirXML is a bidirectional data sharing service designed to solve these types of corporate nightmares. Acting as a central data store, DirXML enables corporations to define policies that control how data is shared throughout the enterprise. The good news is that DirXML enables this sharing to occur without making changes to your existing applications. It communicates with the applications using their existing APIs, change logs, and so on.

DirXML enables administrators of each system to define what data is shared. This helps ensure that corporate data is only accessible to those employees authorized to see it. The administrators also determine which system is the authoritative source for each data attribute. In other words, the administrators may want to specify that the HR system is the authoritative source for all employee names. If the HR system receives a new employee name, then all other applications that want to receive the name will receive it. If a new employee is added to the e-mail system, no other application will receive it because it is not the authoritative source.

Once these types of policies are established, the data is then shared between the applications in real-time. When new employees are hired, the approved data is disseminated to the other applications immediately and accurately. When an employee leaves the company, the employee is removed from all of the applications instantly.

DirXML provides a secure central data store (Novell eDirectory) for all data shared between applications. This means that programmers only need to write to the eDirectory interface to access the information they need. This greatly simplifies their work by reducing the number of applications to be interfaced. If you already have an existing directory, don't worry. DirXML does not require you to replace your existing directory. DirXML enables the sharing of data with the most common directories on the market today.

Components of DirXML

The DirXML architecture consists of the three basic components: the DirXML engine, DirXML Drivers, and the Remote Loader.

  • The DirXML Engine (also referred to as the Join Engine) is responsible for the application of corporate policies, data storage, and data dissemination from the common data store (eDirectory). These policies are communicated to the engine via XML documents called Rules and Stylesheets.

  • The DirXML Drivers are responsible for communication with each application that wants to publish or subscribe data to or from the data store. Novell and third party vendors offer drivers that connect with many of the most common applications.

  • The Remote Loader enables DirXML to provide its data sharing capabilities to applications that are running on remote systems. This data is passed over an IP connection using SSL, making the transfer of the data secure.

The Reporting & Notification Service (RNS)

With DirXML acting as the central hub for data sharing within a corporation, it is critical that all DirXML components function properly. When important events occur, it is imperative that system administrators be notified immediately, by whatever means are best suited to their specific environment. This need has driven the development of the RNS.

RNS allows the administrator to configure the system to provide notifications concerning: fatal errors, errors, warnings, retries, and successes. It also records additional information such as the channel, driver, and objects involved with that event. RNS is not limited to supporting DirXML. Other applications may utilize this service as well. Any application can pass the RNS XML documents containing any type of information that they want to record. RNS messages may also be generated from within DirXML stylesheets.

DirXML 1.1 delivered the first phase of the RNS. In version 1.1, the requested messages were written to just the local driver set object, and the publisher and subscriber objects. This enabled administrators to easily locate all information associated with a specific object. While this approach is an improvement over previous versions of DirXML, it did not offer all the flexibility needed by administrators. As an example, to locate DirXML message information, the administrator must see the error on the trace screen or open each driver object in ConsoleOne and check for errors.

DirXML 1.1a will provide administrators with the second phase of the RNS. In addition to the functionality offered in DirXML 1.1, this update will allow information messages to be optionally recorded to an XML file, or to an LDAP directory. If desired, RNS can also generate e-mail messages or SNMP traps. This gives administrators full flexibility to receive notifications how and where they want. Also, by providing the option to export notifications in an XML file, it opens up opportunities to format the data with third-party reporting tools (see "Using Crystal Reports to Format RNS Output" later in this AppNote).

How Is RNS Information Stored?

DirXML information received by the RNS is recorded in the DirXML Driver-Set object, the Publisher object, and the Subscriber object. The Driver-Set object contains an attribute called DirXML-DriverTraceLevel. This attribute determines the type of information sent to the trace file and to the Publisher and Subscriber objects. The Publisher and Subscriber objects have three attributes used for storing RNS information:

  • DirXML-LastLogTime records the last time that and error or warning was logged.

  • DirXML-StatusLog contains the actual error/warning message and object names.

  • DirXML-LogLimit defines the minimum and maximum number of events that can be stored for this object.

The number of messages stored in each of these objects is fully configurable. If there are multiple instances of a driver running, then each instance will have its own RNS information.

How Is the RNS Administered?

DirXML 1.1a is being released at the same time as eDirectory 8.7. This new release of eDirectory contains iManager, Novell's new role-based management console. DirXML 1.1.a delivers a number of iManager-based plug-ins that enable the management of DirXML over the Web. One such plug-in provides the user with the ability to configure the Reporting & Notification Service.

When launched, the iManager Web interface lists the available roles in the menu on the left side of the screen (see Figure 1).

List of roles and tasks displayed in the Novell iManager utility.

Before configuring the RNS, you must first identify which server will perform the log file operations. To do this, select the Log File option under the eDirectory Maintenance Utilities role. You are then asked to select a server connection from the cached list, select the server object in eDirectory, or specify the server's DNS name (or IP address) and the eMBox port. This defines which Server object will contain the configuration information. This only needs to be done once.

Now that you have specified the Server object to be used, you are ready to configure the RNS. Select the Modify Object link under the eDirectory Administration role on the iManager menu. Enter the name of the Server object used by the RNS. If you are not sure what to enter, click the Object Selector icon next to the Object Name field. This control will allow you to browse for the name of the server object. Once you have properly entered the server object name in the Object Name field, click the OK button.

iManager will now display the Modify Object Web interface. Click the Report & Notification tab (notice that on the tab menu you are given the option of displaying the current configuration view or directly editing the XML file that contains the configuration information). The view shown in Figure 2 is displayed.

The Modify Object "Global Configuration" view in iManager.

The Global Configuration view enables the administrator to define the default methods for the handling of RNS information. Notice that the default is for "All Messages" to be logged to a log file called STATUSLG.LOG. You can specify the maximum size of the file, whether time stamps are recorded, and how often the messages are cached and refreshed.

The RNS supports a number of logging devices: e-mail Messages, DS Events, or an LDAP Directory. Messages going to the specified device can be optionally filtered based upon the type of message: Remote Loader, Application (General, Authentication, or Connection), Driver (General or Status), Password Set Operations, or messages of Unspecified Type.

If you don't want to use the default configuration, the RNS allows the creation of Module Configurations that define object- or service-specific exceptions to the Global Configuration settings (see Figure 3).

The Module Configuration settings in iManager.

As you can see, in the Module Configuration view (visible by scrolling further down the Web page), I have specified that fatal messages from the application or the Remote Loader should be e-mailed to the administrator. You can see the power and flexibility that this offers network administrators.

Using Crystal Reports to Format RNS Output

Crystal Reports 8.5 provides the CR XML ODBC driver. This driver uses ODBC to extract data from an XML document and then formats it inside of Crystal Reports. Since the Reporting & Notification Service saves its log files in XML format, this makes an easy way for Crystal Reports owners to format the data into a report format that is much easier to review than pure XML.

To show how easy this is, let's walk through the steps to configure the driver for use with RNS XML output. Here is some sample XML output from the RNS.

<?xml version="1.0" encoding="UTF-8" ?> <status-log> <status level="error"> <application>DirXML</application> <module>DirXML_DSet</module> <component>engine</component> <description>Multiple Subscriber objects per Driver Set are not allowed</description> <code>-611</code> <object-dn>.cn=DirXMLDriver.O=Novell.</object-dn> </status> <status level="success" type="driver-status"> <application>DirXML</application> <module>DirXML_DSet</module> <component>engine</component> <description>Driver state changed to Running</description> <object-dn>.cn=DirXMLDriver.O=Novell.</object-dn> </status> <status level="warning" type="driver-status"> <application>DirXML</application> <module>DirXML_DSet</module> <component>engine</component> <description>Driver state changed to Stopped</description> <object-dn>.cn=DirXMLDriver.O=Novell.</object-dn> </status> <status level="error"> <application>DirXML</application> <module>DirXMLDriver</module> <component>Publisher</component> <server>.cn=NCPServer.OU=Servers.O=Novell</server> <description>removeEntry: -629 ERR_ENTRY_IS_NOT_LEAF</description> <object-dn>.OU=Employees.O=Novell.</object-dn> </status> <status level="error"> <application>DirXML</application> <module>DirXMLDriver</module> <component>Publisher</component> <server>.cn=NCPServer.OU=Servers.O=Novell</server> <description>createEntry: -611 ERR_ILLEGAL_CONTAINMENT</description> <object-dn>\User1</object-dn> </status> <status level="error"> <application>DirXML</application> <module>DirXMLDriver</module> <component>Publisher</component> <server>.cn=NCPServer.OU=Servers.O=Novell</server> <description>createEntry: -646 ERR_BAD_NAMING_ATTRIBUTES</description> <object-dn>\User2 (\T=Tree_Name\O=Organization)</object-dn> </status> <status level="warning"> <module>DirXMLDriver</module> <application>DirXML</application> <component>Subscriber</component> <server>.cn=NCPServer.OU=Servers.O=Novell</server> <description>nameToID: -601 ERR_NO_SUCH_ENTRY</description> <object-dn>\Novell\User3</object-dn> </status>

This log file has been saved with the filename STATUSLOG.XML. To use the Crystal Reports CR XML ODBC driver to read this file, you must first configure an ODBC Data Source so the driver will know where to find the file.

Configuring the ODBC Data Source

To set up an ODBC Data Source, follow these steps.

  1. Make a copy of your RNS log file and save it with an .XML extension (when you configure the RNS you can specify that the file always be saved with an "XML" extension). I saved my log file with the name STATUSLOG.XML.

  2. Open the ODBC Data Source Administrator (see Figure 4). This utility is found in the Windows Control Panel or in the Administrator Tools folder in the Control Panel.

    ODBC Data Source Administrator utility main screen.

  3. Create a new data source by clicking the Add button. You will be shown a list of the available ODBC drivers, as shown in Figure 5. Select the CR XML v3.6 driver and then click Finish.

    Selecting the driver for the new data source.

  4. The ODBC XML Driver Setup dialog is displayed (see Figure 6). On the General tab, enter the name that you want to give this data. Since I named my file STATUSLOG.XML, I enter "statuslog" in the Data Source Name field. Enter any descriptive text you want in the Description field. In the Location field, enter the directory path where your XML file is located (for example, c:\xml\logfiles).

    The ODBC XML Driver Setup dialog.

  5. Next click the Advanced tab. In the resulting dialog (see Figure 7), make sure the Validate Schema and Resolve External References check boxes are checked. Uncheck the Require User Id / Password check box. All other options should be left in their default positions.

    The ODBC XML Driver Setup dialog.

  6. Click the OK button. You will now see your new Data Source Name appear in the User Data Sources list box, as shown in Figure 8.

    The new driver appears in the list of User Data Sources.

Generating the Report

To generate the report in Crystal Reports, follow these steps.

  1. If you have not done so already, open the Crystal Reports application. At startup, Crystal Reports should display the Welcome to Crystal Reports dialog. If the dialog is not displayed, select "New" from the File menu. Select "Using the Report Expert" (see Figure 9) and click OK.

    Selecting the option to use the Report Expert in Crystal Reports.

  2. The Crystal Report Gallery dialog is displayed (see Figure 10). Make sure the Standard expert is selected, and then click OK.

    Selecting the Standard expert in Crystal Reports.

  3. The Standard Report Expert dialog shown in Figure 11 is displayed. Click the Database button.

    Selecting a Database report in Crystal Reports.

  4. The Data Explorer dialog shown in Figure 12 is displayed. Click the "+" sign next to the ODBC folder to expand its contents.

    The Data Explorer dialog in Crystal Reports.

    Scroll down the list until you see the Data Source Name that you created. Click the "+" sign next to the Data Source Name. The list will now display all of the XML files in the directory referenced by your Data Source Name. Select the file you want to use (the files are displayed in XML.<filename> format) and click Add. Then click Close.

  5. The filename will now appear in the Tables list box of the Standard Report Expert dialog (see Figure 13). Click the Next>> button.

    The Standard Report Expert dialog in Crystal Reports.

  6. The Fields tab is now displayed, as shown in Figure 14. Click the Add All-> button to move all of the Available Fields into the Fields to Display list box. Click Finish.

    The Fields tab in the Standard Report Expert dialog.

The report that is displayed is shown in Figure 15.

Sample report displayed by Crystal Reports.

You probably noticed that the Description and Object-dn fields are truncated. This is easily corrected by making formatting changes within Crystal Reports.

Conclusion

To summarize, the critical role that DirXML plays in an enterprise requires that administrators be kept aware of the status of the system. The Reporting & Notification Service gives administrators great flexibility regarding how errors, warnings, and other critical messages are received and recorded. Since the RNS log file is saved in XML format, it provides an easy method for generating well-formatted reports using tools such as Crystal Reports.

* Originally published in Novell AppNotes

Disclaimer

The origin of this information may be internal or external to Novell. While Novell makes all reasonable efforts to verify this information, Novell does not make explicit or implied claims to its validity.

© Copyright Micro Focus or one of its affiliates