1.4 Basic Functionality of the Avaya PBX Driver
1.4.1 New Objects Used by the Driver
Using four new object classes in eDirectory, the Avaya PBX driver performs work orders, records the results, and provides extension information. The Avaya driver also supports Audix account provisioning. For a description of the schema for these objects, see Section B.0, Schema for PBX Management.
DirXML-pbxSite
DirXML-pbxSite represents 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. In iManager, select . The following figure shows an example of the interface for setting up a PBX site.
Figure 1-2 The PBX Site Page
nwoWorkOrder
DirXML-nwoWorkOrder represents 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. In iManager, select . The following figure shows an example of the interface for creating a work order.
Figure 1-3 The Work Order Page
pbxExtension
DirXML-pbxExtension represents 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.) If you create a new Audix-Subscriber object, a new DirXML-pbxAudixSubscriber object is sent to the engine.
pbxAudixSubscriber
DirXML-pbxAudixSubscriber represents Audix support.
With Audix support for the Avaya driver, the driver can add voice mail to an extension, remove voice mail from an extension, or modify the attributes of the voice mail of an extension. However, this driver support does not replace general administration of the Avaya Audix system.
Adding Audix support to the current Avaya driver requires the driver to access and manipulate PBX subscriber objects. This is performed by extending the eDirectory schema to include a DirXML-pbxAudixSubscriber object and by adding a new site object that defines the Audix server.
1.4.2 Overview of Driver Functionality
When configuring the driver, you have the option to run the driver in emulation mode. Although 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, 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 the Identity Vault representing the change.
-
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.
-
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 Installation work orders, the Publisher also sends a DirXML-pbxExtension object to the Identity Vault 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 the Identity Vault with the new extension in the DirXML-nwoExtension attribute.
-
For Add Audix Subscriber work orders, the Publisher also sends a new DirXML-pbxAudixSubscriber object to the Identity Vault.
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 immediately processed by the Publisher channel.
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:
-
Create a work order when a new user object is added to the Identity Vault in order to automate an extension assignment to a new employee. This could be further automated by using an additional Identity Manager driver to automatically create user objects in the Identity Vault 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 the Identity Vault. 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 order objects from another application to be synchronized to the Identity Vault and performed by the Avaya PBX driver.
-
Transform an add DirXML-pbxExtension object coming from the driver into an add and a modification of a User object, so you can update the User object with the new extension when a work order completes.
-
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:
1.4.3 Assumptions about the PBX
The PBX is the Public Branch Avaya PBX or corporate phone system. The PBX can 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 is physically cross-connected to a PBX digital port.
Because the driver is designed to be generic, the PBX can be used in any environment, from an enterprise call center system to a small office key system.
The Avaya PBX driver 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.
Voice Jacks
The behavior of the driver depends 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 is followed. (See Cold Jacks.) The driver assigns the port specified in the work order. If no port is specified, the driver will “X out” the port.
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 assigns the first available number in numeric order. When the phone is delivered and plugged in, punching in a code activates the extension on that phone by automatically assigning the port (if the port was “Xed out.”)
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 assigns 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. When the phone is physically installed, the driver sees the change after its next polling cycle and changes the status of the work order.
Querying the PBX
Because of the limitations of the PBX system, the driver queries the PBX only for DirXML-pbxExtension and DirXML-pbxAudixSubscriber extensions.
The PBX doesn’t support queries on the display name or the field containing a user identifier. To find those pieces of data when querying the PBX, you need to create a custom policy 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.
1.4.4 What the Driver Does in the PBX
At the most basic level, the driver can perform several actions in the PBX: install, disable, enable, move, modify, setcor, and 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 assigns 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 assigns 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: Move an extension in one of the following ways:
-
Deactivate it in one location and activate it in another location within the same PBX system.
-
With the use of custom policies, deactivate it in one PBX system and activate 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: Remove an extension from the PBX.
-
Set values such as the following, based on data you provide in the work order:
-
The date to complete the desired action.
If the DoItNow flag is set, the driver performs the action immediately.
The driver is configured so that at a specified time once a day it performs 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).
-
-
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 extensions. This feature is available in Avaya PBX but not in Audix.
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, and the driver is 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 object ID is inserted the label 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 object ID into the label field, the driver discovers that change and automatically updates the user object with the new extension.
1.4.5 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 test environment. When you are comfortable with the test environment, you can move into production. Most companies, however, don’t have PBX systems dedicated to 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. Instead of connecting to the PBX, the driver is able to add, modify, and delete extension and Audix Subscriber 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.
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 PBX name in 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 a DirXML-Extension object was created.
1.4.6 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 also supported.
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 the Identity Vault to reflect changes that have been made manually, as much as possible.
The following table indicates 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.
Table 1-1 Changes the Driver Can Detect in the PBX