Novell Documentation: Nsure Identity Manager Drivers - Basic Functionality of the Driver

Basic Functionality of the Driver

In this section:

New Objects Used by the Driver

Using three new object classes in eDirectory, the Identity Manager Driver for Avaya PBX performs work orders, records the results, and provides extension information. The new objects are

DirXML-pbxSite to represent the PBX.
The driver depends on the information in PBX Site objects to know which sites to manage, and how to connect to them.

An iManager plug-in is provided to help you set up these sites, PBX Utilities > Site Management. The following figure shows an example of the interface for setting up a PBX site.
DirXML-nwoWorkOrder to represent work orders.
This object lets you indicate what actions you want the driver to perform in the PBX, and specify other details such as when the work order should be performed, the object ID and display name of the person who owns the extension, and whether a specific extension number is requested. After the driver performs the work order, it updates the work order with information such as the status (Configured, Error, etc.).

An iManager plug-in is provided to help you create and maintain work orders, PBX Utilities > Work Order Management. The following figure shows an example of the interface for creating a work order.
DirXML-pbxExtension to represent extensions
After performing a work order, the driver shim sends one of these objects to represent the work that was done. For example, if a new extension was configured, a new extension object is sent with the correct extension number and display name. The driver updates the work order with information such as the status (Actions taken if successful, Configured, Error, etc.)

For a description of the schema for these objects, see Schema for PBX Management.

Overview of Driver Functionality

When configuring the driver, you have the option to run the driver in emulation mode. While this mode of driver operation is optional, we highly recommend its use. Emulation mode enables you to fully test the driver and its policies before connecting to a live PBX system. When you run in emulation mode, the driver emulates the PBX specified by the pbxSite object. All driver actions are directed to the LDAP site that you specify in the Configuration Parameters. To run in emulation mode, locate the pbxSite object and set the DirXML-AccessType attribute to "emulate." This causes the driver to emulate the PBX. For more information, see What is Emulation Mode and Why Should I Use it?.

The driver shim itself functions in the following basic way:

When the driver starts up, it reads the information for the DirXML-pbxSite objects from the container you specified in the driver parameters.
These objects tell the driver which PBXs to perform work orders on, and they provide other details such as which number ranges can be used for extensions.
At the polling time or interval you set, the driver shim "wakes up," and the Publisher queries the PBX for all the extensions. If it detects that a change has been made manually since the last polling interval, it sends a DirXML-pbxExtension object to eDirectory representing the change.
See Support for Manual Changes in the PBX.
The Publisher then polls for DirXML-nwoWorkOrder objects in eDirectory in the container you specified in the driver parameters. It checks the DirXML-nwoDueDate and DirXML-nwoStatus attributes on the work orders to see which of them need to be performed.
NOTE: For many drivers, the Subscriber performs changes in the third-party application in response to events in eDirectory. However for this driver, the Publisher is the agent which performs work orders in the PBX. The Subscriber merely picks up events such as Add User events, creates work orders if configured to do so, and sends work orders to the Publisher if they are marked "Send to Publisher" or "DoIt Now." The Subscriber does not listen for events pertaining to pbxSite objects, so if changes are made to these objects you must stop and restart the driver for the changes to be recognized by the driver.

There are several reasons for this design; for example the Publisher has the ability to run at a certain time of day, which is desirable for allowing you to specify that work orders be performed after business hours.
The Publisher performs the work orders that are due, completing the appropriate action based on attributes of the DirXML-nwoWorkOrder objects. If a value was present in the work order for the DirXML-nwoObjectID attribute, the Object ID is placed in the Cable field for that extension in the PBX.
The Publisher updates the DirXML-nwoWorkOrder with the results.
For example, if a work order to install a new extension is successful, the DirXML-nwoStatus attribute is updated with the value "Configured." If no extension number was requested in the work order, or if the requested extension was not available, the Publisher specifies which extension was chosen.
For install work orders, the Publisher also sends a DirXML-pbxExtension object to eDirectory for each work order, representing the results.
For example, if a work order to install a new extension is successful, a DirXML-pbxExtension object is sent to eDirectory with the new extension in the DirXML-nwoExtension attribute.

The driver can also perform a work order immediately instead of waiting for the next polling interval, if you indicate "Do It Now" in the work order. Work orders with this attribute are sent to the Subscriber channel, which sends them to the Publisher channel to be performed.

You can customize the driver to enhance what it does. The sample configurations demonstrate some of these customizations.

For example, you can use driver policies to do the following:

Cause a work order to be created when a new user is added to eDirectory, to automate the assignment of an extension to a new employee. This could be further automated by using an additional Identity Manager driver to automatically create users in eDirectory when they are created in a human resources application.
Assign certain phone restrictions based on the location or job title indicated for the user object in eDirectory. For example, you could configure the driver to use non-DID extensions for employees in the call center.
Using an additional Identity Manager driver, cause work orders from another application to be synchronized to eDirectory and performed by the Avaya PBX driver.
Transform a new DirXML-pbxExtension object coming from the driver into a modification of a User object, so you can update the User object with the new extension when a work order is completed.
Add other customizations to fit your business processes.

To demonstrate some of the things you can do with the Avaya PBX driver, two sample driver configurations are provided. A third kind of configuration is also described in this guide, but the sample scripting provided is not a complete driver configuration.

These three kinds of configurations are discussed in the following chapters:

What is Emulation Mode and Why Should I Use it?

For all new Identity Manager products, we recommend that you configure and use them first in a testing environment. When you are comfortable with the test environment, you can move into production. Most companies, however, don't have PBX systems available for testing. To aid you in testing and debugging, the driver has a built-in emulation mode. In emulation mode, you configure the driver as if you were connecting to your PBX system. But instead of connecting to the PBX, the driver is able to add, modify, and delete extension objects in an LDAP container-which is simulating the PBX. You can fully test policies without affecting the live PBX. It enables you to make PBX changes more easily because you can simulate and watch work order processing before moving to a production environment.

How Does Emulation Work?

When the driver loads and detects the emulation settings, it uses the emulation parameters set during configuration. The driver binds to the LDAP directory and looks for a PBX site container that holds extensions. If this container does not exist, the driver creates a container with the same name as the site object. During emulation, this is the container the driver looks for when making changes to extension objects. All read/write activity occurs in the PBX site container, and the driver treats the container like it is a PBX system. If a work order is created to install a new extension, you should look in this container to verify that it was created.

How Do I Configure Emulation Mode?

When configuring the driver's parameters, there are five parameters (in the Publisher settings) that you need to specify in order configure the driver for emulation. They are:

The IP address of the LDAP host you want to use for emulation. This can be eDirectory or any other LDAP directory.

The LDAP port that the host uses for LDAP.

The DN of the login user on the LDAP host you are using.

The password of that user.

The DN for the container that will hold the emulated extensions.

For more information on these settings, see Setting the Driver Parameters for Emulation.

What the Driver Does in the PBX

At the most basic level, these are the actions that the driver can perform in the PBX: install, disable, enable, move, modify, setcor, disconnect. The following list describes the main tasks you can perform using work orders.

Install: Assign an extension in the PBX at a given location, and activate the extension.
You can request a specific extension number, and the driver will assign that number if it's available in the PBX. If it's not available, or if no extension is specified in the work order, the driver will assign the next available extension number in numeric order within the range of extensions specified in the PBX site object.
Disable: Stop allowing an extension to be used, but leave it installed in case you want to enable it again in the future.
Enable: Allow an extension to be used again after it has been disabled.
Move an extension in one of the following ways:
- Deactivating it in one location and activating it in another location within the same PBX system.
- With the use of custom style sheets, deactivating it in one PBX system and activating it in another PBX system.
Setcor: Use the setcor command to change restrictions for the extension, such as whether long distance or international calls are allowed.
Disconnect: Delete an extension from the PBX.
Set values such as the following, based on data you provide in the work order:
- The due date to complete the desired action.
  If the DoItNow flag is set, the driver will perform the action immediately.
  
  The driver is configured so that at a specified time once a day it will perform work orders that are due that day. You can also set a polling interval for performing work orders.
- The type of phone (DID or non-DID).
- Restrictions for use of the phone extension, such as whether long distance or international calls are allowed.
- The port number for the phone connection (necessary if you use cold jacks).
Perform the work order either immediately (using the DoItNow flag) or on a specified due date.
You can set the driver to check for work orders at a certain time each day or at a specified polling interval.
Query the PBX to find out what manual changes have been made since the last time the driver polled for work orders. This feature supports manual changes to the PBX.
At the specified time of day or polling interval, the Publisher "wakes up" to perform work orders. Before polling for and performing work orders, the Publisher first queries the PBX to find out whether anything has changed since the last time the Publisher performed work orders. This means that you can make changes manually in the PBX if necessary, and the driver will be made aware of those changes when it next communicates with the PBX.

This feature makes the driver implementation more flexible, because you are not limited to making changes only through the driver. In addition, if you make sure the employee ID is inserted the definition field in the PBX whenever you make a manual change, you can use this feature to automate updates to user objects to reflect changes in the PBX made manually, as well as changes made by the driver. For example, in the workforce tree sample configuration, if you install an extension and insert the employee ID into the definition field, the driver will discover that change and automatically update the user object with the new extension.

See Support for Manual Changes in the PBX.

Explanation of DoItNow and SendToPublisher Flags

DoItNow Flag

When this flag is set to true for a work order, the Subscriber "wakes up" the Publisher by sending the work order to the Publisher. The Publisher performs the task immediately instead of waiting for the next polling time or polling interval.

This flag is useful in a situation where you want the work order to be completed right away. You can set this flag to true when you manually create a work order, or in an automated solution you can use policies to determine whether the flag should be set. For example, you could configure the driver to set the DoItNow flag to true for an incoming work order if a corresponding attribute is set in a work order database. As another example, you could configure the driver to set the DoItNow flag to true if an Install work order is triggered by a new user in a human resources application.

SendToPublisher Flag

When this flag is set to true for a work order, the Subscriber sends the work order to the Publisher, and the Publisher writes the work order object in the correct container according to the work order container specified in the Configuration Parameters.

This flag is not necessary in implementations where the work order object is created in eDirectory by an administrator (as in Base Configuration) or an application (like the solution described in Work Order Database Configuration).

The scenario where this flag is useful is one in which the work order is triggered by another eDirectory event through the use of a policy or style sheet, and the work order does not yet exist in eDirectory as an object. This kind of scenario is described in Workforce Tree Configuration.

Assumptions about the PBX

The PBX is the Public Branch Avaya PBX or corporate phone system. The PBX may be centralized or distributed across buildings or sites. A PBX system can be composed of several PBX cabinets, including remote cabinets, controlled by a master PBX cabinet. Typically, each phone will be physically cross-connected to a PBX digital port.

Since the driver is designed to be generic, the PBX may be used in any environment, from an enterprise call center system to a small office key system.

The Identity Manager Driver for Avaya PBX relies on the following assumptions:

Responsibility for PBX administration lies with the user rather than a third party.
The PBX administrator has sufficient training and certification, and appropriate access rights to the PBX.
The PBX supports administration by telnet.
Voice jacks are either "hot jacks" or "cold jacks."
The driver supports both kinds of environments. See Voice Jacks, below.

In this section:

Voice Jacks

The behavior of the driver will depend on whether or not the PBX environment has hot jacks (jacks that are permanently cross-connected to live PBX ports) or cold jacks (jacks that are cross-connected at the time of phone installation).

Hot Jacks

Hot jacks are simpler from a configuration standpoint, if the PBX supports port selection from the phone set. If the PBX does not support port selection from the phone set, the cold jack process will be followed. (See Cold Jacks.)

When a work order requests a new phone, the driver creates the extension in the PBX, but leaves the port unassigned. If the work order did not request a specific extension number, the driver will assign the first available number in numeric order. When the phone is delivered and plugged in, punching in a code can activate the extension on that phone by automatically assigning the port.

When moving an existing extension, the driver simply unassigns the port, meaning it is "Xed out." This deactivates the extension. When the phone is delivered and plugged in at the new location, punching in the activation code will assign the new port to the extension.

Cold Jacks

If the PBX environment has cold jacks, the installation process requires you to specify which node the user is in as part of the work order. If the extension is not given, the next available number is assigned. The driver also scans for available ports that work with the phone type and are in the correct node. The new port is assigned to the extension and is noted in the work order.

When the phone is delivered, a technician must cross-connect the port to the new jack.

If you have cold jacks, but you prefer that the driver "X out" the port instead of automatically choosing one, you can specify the hot jacks option.

Querying the PBX

Because of the limitations of the PBX system, the driver queries the PBX only for extensions.

The PBX doesn't support queries on display name or the field containing a user identifier. To find those pieces of data when querying the PBX, you would have to create a custom style sheet configuration that queries the PBX for all the extensions and their associated data, and then searches through the entire list to find the value you want.

Support for Manual Changes in the PBX

The preferred method of performing PBX tasks is to create a work order and let the driver configure the PBX. However, manual changes made in the PBX are supported as well.

When the driver prepares to perform work orders, at the polling interval or time of day you specify, it first queries the PBX for the extensions to see if anything has changed since the last time the driver communicated with the PBX. This functionality allows the driver to update eDirectory to reflect changes that have been made manually, as much as possible.

Here are the changes the driver can detect in the PBX if the changes were made manually, and what the driver can do in response to them.

Change made manually in the PBX	Can the driver detect the change?	Can the driver update eDirectory in response to the change?	How the driver can update eDirectory
Install a new extension	Yes	Yes, if the ObjectID is entered correctly in the PBX.	The driver creates a new nwoExtension object.
Modify the display name	Yes	Yes, if the ObjectID is entered correctly in the PBX.	The driver modifies the DisplayName attribute of the nwoExtension object. (In the workforce tree configuration, no change would be necessary.)
Modify the ObjectID	Yes	Yes, if the ObjectID is entered correctly in the PBX.	The driver can update the nwoExtension object with a new ObjectID. It's preferable to use two work orders, one to disconnect the extension for the first user, and another to install the extension for a different user.
Setcor	No	No update to eDirectory is necessary.
Disable an extension	Yes	Yes	The driver
Disconnect an extension	Yes The driver detects that this extension is not connected and is available for reuse.	No	In the base configuration, the driver can delete the nwoExtension object that represented the extension. It can do this by querying for the nwoExtension that has the corresponding extension number in the Extension attribute. ???(In the workforce tree configuration, the driver updates all users who have this extension in their phone list, by removing the extension from the list. Instead of relying on the ObjectID in this case, the driver determines which users to update by querying eDirectory for User objects that have that extension.)