Skip to end of metadata
Go to start of metadata

The VX Active Directory (AD) feature provides centralized authentication and authorization services for Windows machines across a domain. Information stored in an accessible database consists of objects, and provides information, control and access to these objects. The objects have attributes that are useful to applications. The information that the objects can contain is defined by a schema which can be extended to contain more attributes.
A VX node functions as an AD client. VX is able to obtain every readable user field in the AD. The LDAP directory database can be queried. Queries consist of column names and row names, at the intersection of which are stored values. When forming queries, two values must be specified. For example, if we know we have a phone number, our column might be "PhoneNumber" and our value would be the actual number. We can use this information to ask for a user's name (user email, user country and so on) whose phone number matches our known value.

VX uses these returned values to create call routes.

There are two aspects that affect accessing data from the AD; the first is security restriction and the second is determining which server to bind to for queries.


Accessing AD values request a user account with appropriate credentials on the particular domain to be queried. VX administrators are required to create a user in the system, preferably one whose credentials never expire. VX uses these credentials when communicating with the AD.

This user can be created using the VX Command Line Interface (CLI) or by way of VXbuilder. When using VXbuilder, see Creating an AD User below.

Domain Membership

Domain membership is not required for VX to query an AD. For VX nodes that are set up and configured to be part of the domain, the global catalog will be used to more efficiently query and collect AD data. However, configuration stand alone workgroup machines are also allowed to query AD data. Configuration requires the domain controller IP address to be specified if not part of the domain.

Call Routes

VX will create routes based on the existence of values in the Active Directory. Active Directory support exists for input and output numbers.

A simple example is provided here to describe this concept.

Suppose all PSTN calls arrive at VX. All OCS users have a Line URI property configured in Active Directory. VX will be able to look up the corresponding value in Active Directory (msRTCSIP-Line attribute). It will form a simple LDAP query, requesting this property, given a particular user's name (for example). If an existing value is found for the user, the call can be routed to OCS (with this value) and it will properly route the call. If this value does not exist, the call could be routed to an existing PBX.


VXScript has access to Active Directory values for call routes. Scripts are able to call into VX Active Directory code, pass in query parameters and receive return values


Values often need to be available even if the Domain Controller cannot be contacted. In order to deal with this issue, Active Directory queries can be cached.

A VX memory container exists for this purpose. It performs the Active Directory query and store the data in a fashion that makes it quickly and locally available.

What Gets Cached

Users get cached based on the organizational unit they belong to. The configuration will require an org unit to be. By default, specifying only an org unit, with no additional fields, means that all of a user's properties will be loaded into the local cache. In order to filter down the amount of data to collect (not all is relevant), the input and output numbers from call routes will be examined, and those values are cached. Furthermore, an additional field exists in the configuration to allow for explicit specification of desired attribute to cache. This field allows the scripting language to define its set of cached values.

Modes of Operation

Active Directory values and schemas change. If values were merely cached once, they would become out of date somewhat quickly. Thus, VX allows for periodic re-caching of Active Directory data. The updates will happen by a configuration specified amount of time.

Due to different needs, configuration allows running with Active Directory in three different modes. The first is without caching. Every Active Directory lookup will query the domain controller to get the results. The second method consists of working entirely offline. Offline mode creates the cache initially and does not query Active Directory for updates. The final mode of operation is an online cached mode. In this mode the cache is populated and queries are run against it. Periodically the cache is refreshed by querying for AD updates.

Return values

The cache always returns a single value when queried. This can be a full user record or just a particular value for an attribute. Values, by nature, should be unique, but in the case that they are not, the first value found is returned. In other words, if a query matches multiple rows, only the first is returned.

System Down

In case the system goes down abruptly, memory mapping (MMH) is supported in flash only systems, in conjunction with online caching mode. The cache contents will be mapped to the system and is used on startup if AD can't be contacted and local memory had been previously saved.

Data Availability

Data is available both in the cache – assuming it can be constructed – as well as by communicating directly with the Domain Controller machine. No restrictions are placed on how to obtain the data; it is driven by the configuration.

Active Directory down

If Active Directory is down or not reachable, the local cached values can be used. If these values become stale and incorrect, the particular resource used to perform call route might not work any longer. Furthermore, not all Active Directory users are created equally, and may not all have all available features. As a result, it is important to create routes that will work in a particular way if the key is found and another way if the key is not found.