LDAP Connect User's Guide
CHAPTER 3
The LDAP Connect for Novell exteNd Composer allows you to build XML integration applications that are directory-aware. In practical terms, this means you can leverage well-established LDAP APIs for:
LDAP's search function emulates the more complex X.500 operations such as list and read. The metaphor is the same: You specify a base object to be searched and the portion (or scope) of the tree to search. A filter specifies the conditions that must be met in order for the search to capture a particular entry. (The LDAP search operation offers identical functionality to DAP's, but is encoded in a simpler form.)
NOTE: While in theory the LDAP API allows applications to perform operations either synchronously or asynchronously depending on whether the client wants to wait for an operation to complete before receiving the results of a previous operation, in actuality all operations in the LDAP Connect for exteNd Composer are synchronous.
In the LDAP Connect, you will issue LDAP queries in DSML (Directory Services Markup Language) form, using an industry-standard query-response syntax, rather than writing your own custom Java code to package and unpackage queries using an LDAP SDK. What makes DSML particularly attractive is that it is XML: You can map data into or out of it easily using ordinary Composer actions. What makes the LDAP Connect particularly powerful is its ability to autogenerate DSML for you, on the fly, so that you don't have to know low-level DSML internals.
LDAP applications typically perform five steps:
Open a connection to the LDAP server. This step involves initializing the session, setting session preferences and binding to the server. Usually the session preferences involve defining things like:
Authenticate to the server. The client can authenticate either anonymously with public rights, or through simple (clear-text) password authentication, or with full encryption. Novell's LDAP Services v3 uses SSL3 for full encryption and authentication.
Perform the operations and obtain the results. This step usually involves searching the directory, but may also involve modifying the directory data as well.
Process the results. This step involves making use of the returned information in some fashion, via custom business logic.
Close the session. This means unbinding from the server and disposing of the session handle. (In Composer, this step occurs automatically when your component goes out of scope.)
As with all exteNd components, the first step in creating a new LDAP component is to determine whether you need any XML templates. (For more information, see Creating a New XML Template in the separate Composer User's Guide.) Providing you've created a Connection Resource in advance (discussed earlier), you can then create an LDAP Component, using your templates' sample documents to represent the inputs and outputs processed by your component.
To create a new LDAP component:
In Composer's main menubar, go to the File menu and select New > xObject, then open the Component tab and select LDAP. The "Create a New LDAP Component" Wizard appears.
NOTE: If your project currently contains no LDAP Connection Resources, you will be prompted to create one at this point, and you will go through the Connection Resource creation process before you reach the above dialog.
Specify one or more Input templates as follows:
Select a Template Category if yours will be different than the default category.
Using the dropdown menu immediately to the right., select a Template Name from the list of XML templates in the selected Template Category.
To add additional input XML templates, click Add and repeat these steps.
To remove an input XML template, click inside an entry and click Delete.
Select an XML template for Output.
NOTE: You can specify an empty XML template by selecting {System}{ANY} as the Output template. You might do this if you wanted to generate a custom Output DOM dynamically using ECMAScript or XPath inside a Map Action. (For more information, see the Composer User's Guide, particularly the chapter on creating an XML Map Component.)
In this dialog, you may (optionally) add Temp documents for use as "scratchpad DOMs" in your component. You may also add Fault documents as needed. Use the Add and Delete buttons to add or remove documents as desired.
Select a Connection from the pull-down list. (The list will be prepopulated with the names of existing LDAP Connection Resources.)
NOTE: You can later change this selection and use a different connection resource, if you want. You are not "locked into" using this connection.
TIP: The fields of the connection resource will be greyed out in this dialog. If you need to edit the connection resource, open it separately after you are done creating the component.
Click Finish. The Composer main window appears, with a blank action model pane. The Native Environment Pane in the upper right should have a Tree tab as well as a Schema tab. (Schema here refers to an LDAP directory schema, not an XML schema.) When the Tree tab is selected, you should see a tree view of the target directory. See below.
At this point, you can begin creating actions in your action model, or you can simply Save your work and come back to the component later.
The LDAP Component Editor includes all the functionality of the XML Map Component Editor. It contains mapping panes for Input and Output XML documents as well as an Action pane. All of the regular Composer actions (such as XML Map, Function, Log, Decision, Send Mail, etc.) are available to you along with the two LDAP-specific actions, Create DSML and Execute DSML. (These actions will be discussed in detail in the next chapter.)
The LDAP Component Editor includes a Native Environment Pane (see graphic above) with a Tree tab offering a browseable tree view of the directory to which your component's Connection Resource points, as well as a Schema tab (discussed in more detail below). If you are familiar with Novell's ConsoleOne tree browser, the Tree tab's browser operates in much the same way.
The Native Environment Pane's default location is in the upper right corner of the main Composer window. You can change its location, however, by using the View > Window Layout menu command:
This command will bring up a dialog in which you can specify North, West, East, and South positionings of the Native Environment Pane, XML document windows, and Action Model pane.
The Tree tab of the Native Environment Pane (see illustration below) offers an interactive design-time visual aid for finding and verifying the location of objects in the target directory. This view will populate automatically when you open a component. Its contents are based on the host specified in the component's Connection Resource.
NOTE: You cannot drag or drop items into nor out of the directory tree view.
The Schema tab (see illustration below) is a read-only design-time aid for inspecting object/attribute relationships as defined by the schema for this particular tree. If your component will contain actions that modify the schema, you can verify the changes visually simply by inspecting this tab. ( "Schema" here refers to the directory schema, not an XML schema.)
To see all of the attributes defined on a given object, simply click any object name in the top scrollpane of the tab; the list of attribute names in the bottom scrollpane updates accordingly in real time.
For additional information on the Composer work environment, consult the separate Composer User's Guide.
Two special tabs—the Request and Response tabs—appear in the Native Environment Pane when an Execute DSML Action is selected (highlighted) in the action-model pane. These tabs (see below) present a tree view of the DSML request/response DOMs that were used by the Execute DSML action during execution.
NOTE: The tabs are initially empty. To populate the tab with the appropriate DOMs, run your action model in animation mode (or by using the Execute All button in Composer's main toolbar), then select/highlight the Execute DSML action.
The request and response DSML DOMs are volatile (transitory) and cannot serve as drag sources nor drop targets. To map to or from these DOM elements, use a Create DSML action to map a batchRequest element to Input (as described in the next chapter), or use an Execute DSML action to map a batchResponse element to Temp, Output, etc.—then drag-and-drop between DOMs (or map DOM contents in whatever way you choose).
Working with DSML DOMs will be described in more detail in the next chapter.
Additional tabs (with names Add, Attributes, Compare, Filter, Modify, Rename, and Search) will appear dynamically when you add Create DSML actions of various "flavors" to your action model. The appearance and usage of each of these will be discussed later.
Composer's UI allows you to drag and drop DOM nodes from one DOM tree to another, or in some cases, from a DOM tree to a field in the Native Environment Pane. This is a convenient, quick way to specify data-mapping rules that would otherwise require hand-coded XPath or ECMAScript expressions.
DOM-to-DOM drag-and-drop allows you to specify data mappings across documents. (For example, you can specify the transfer of data from a particular spot in a DSML response document to a special location in a custom DOM.)
When you click on a DOM element in (for instance) the Input DOM, in tree view, and drag it into another DOM window, then release the mouse when it is over a particular element, Composer maps a copy of the source's data, attributes, and children (including their attributes, etc.) into the target element (the "drop target"). At the same time, Composer automatically adds a Map Action, corresponding to the mapping that just occurred, to your component's action model.
In many cases, the map-all-descendants behavior just described is what you will want. But in some cases, you may need different mapping behavior. For more precise control over data mappings, you will want to create Map Actions manually and use the Map Action dialog (and its Advanced button) to achieve the desired mapping(s).
NOTE: These techniques are described in detail in the Composer User's Guide. Consult that guide for more information.
In many instances, you can click on a DOM element in (for instance) the Input DOM, then drag that element to a text field in the Native Environment Pane and let go, thereby populating the target field with a reference to a particular XML element.
Consider the following example:
In this example, the user is constructing a search filter and is taking advantage of drag-and-drop to bind a node in the Input document to a parameter in the filter expression. The user has clicked the cn node under ADDREQUEST in Input, and dragged it to the empty field in the Native Environment Pane. When the mouse is released, the appropriate ECMAScript expression, namely Input.XPath("ADDREQUEST/sn"), will appear in the target field of the search expression. Thus, the filter (as constructed) will match entries where objectClass equals inetOrgPerson and sn equals the value in Input/ADDREQUEST/sn.
Menu commands specific to the LDAP Connect include two new actions (Create DSML and Execute DSML, both under Action > New Action) as well as two commands under the Component menu:
The Refresh LDAP Schema command updates the contents of the Schema tab (discussed above). This command has no runtime significance. It is potentially useful at design time in cases where you've modified the target directory's schema in some way and want to see the change(s) reflected through to the Schema tab contents in Composer.
Likewise, the Refresh LDAP Tree command (which has no runtime effect) is useful when you have modified the contents of a directory at design time by executing DSML requests—such as Add or Rename—and want to see the changes reflected in the Tree tab in the Native Environment Pane.
Copyright © 2003 Novell, Inc. All rights reserved. Copyright © 1997, 1998, 1999, 2000, 2001, 2002, 2003 SilverStream Software, LLC. All rights reserved. more ...
