Customizing Directory Manager

Directory Manager is customized almost entirely by editing option files. Most of these files take the format of an XML file. Prior to starting the customization work, we have afew recommendations:

  • Remember, XML is much pickier than HTML. Tags names and options are often case sensitive and all open tags must have a close tag

  • Get a good text editor – Notepad++ is both very good and free

  • Always make backup copies of configuration files before editing them


The configuration files are as follows:

  • DirectorySettings.xml – This is the primary configuration file; this is the file you will edit most often. It controls the fields that are visible/hidden, field labels, dropdown list options, field types, validation formats, required fields, default values, and more. When you edit this file, you may find many attributes that you did not realize exist in the Active Directory. There are many attributes that Microsoft does not use.

  • AppSettings.xml – This file controls options such as help text, logging, e-mail notification, error message text customization, button labels, and filtering options for lookup boxes like the Manager box. This file also controls the options that are available on the search interface and the maximum number of search results.

  • AddressSettings.xml – This file controls the Address Sets feature. The Address Sets feature allows the end user to pick a field (such as Office) and automatically have other fields filled in automatically (such as street address, city, state, country, etc..) Once you create a list of offices, for example, and enable Address Sets, the office list no longer needs to be maintained in the DirectorySettings.XML file.

  • SubSettings.xml – This file allows you to define a parent-child relationship between 2 attributes. For example, you can define a relationship between a division and a department. If the user selects the “Information Technology” division, then they would only see a list of departments within that division.

  • PasswordSettings.xml – This file is used to define password policies if you enable the Password Management tab.

  • Style.css – This is the cascading style sheet. This can be used to change fonts, screen colors, and screen width. Changes to this file can negatively affect the interface so only experienced web site developers should edit this file.

  • Web.Config – This file is the web application file. Typically, the only useful thing you can do in this file is to enable Integrated Windows Authentication.

The primary changes that most customers want to make are handled via the DirectorySettings.XML file. This file allows you to:

  • Change an attribute/field’s screen label
  • Set the field type (dropdown, text, combo)
  • Add values for fields that use dropdown lists.
  • Hide / show a field
  • Make a field editable/read only
  • Set a default value for a text field
  • Make a field required
  • Define a validation format
  • Set a field to be double-wide
  • Set a field to be multi-line
  • Provide some example text below the field

Here is a typical “tag” from the DirectorySettings.xml file. The tag consists of the field name as well as options for that field that enable or disable particular features. This tag is for the company field:

<field id="company" label="Company" attribute="company" visible="true" editable="true" type="dropdown" maxLength="64">
<value>Company 1</value>
<value>Company 2</value>
<value>Company 3</value>
<value>Company 4</value>
</company>

This "tag" produces a field on the Directory Manager whose label is "Company", the type is a drop-down list, and there are 4 options in the drop-down list.

Directory Update - Sample field

Note with drop-down lists, if there is an existing value in the Active Directory and it is NOT one of the values in the dropdown list, then it will not be displayed in the dropdown list.


Label

The label=“Company” option displays the text “Company” next to the field.


Field Type

The type=“dropdown” option allows you to define the field type. Valid field types are:

  • dropdown
  • text
  • combo
  • maskedText

The text box allows the user to enter data in free-form text with no validation or control. The combo box has a drop-down list but the end user can enter free-form text also.

The other option (maskedText) is best used with phone number fields and allows you to define input guidance or field formatting. For example, you could use a maskedText option if you wanted a user to enter a phone number in a specific US format, such as this:

Directory Update - Masked text field

Below is an example of using the maskedText option for the office phone number field:

<field id="officePhone" label="Office Phone" attribute="telephoneNumber" visible="true" editable="true" type="maskedText" 
mask="(###) ###-####" maxLength="64" validationFormat="" />

Visible or Hidden Fields

A field can either be hidden or visible on the interface. visible=“true” displays the field while visible=“false” hides the field.


Editable or Read Only Fields

A field can be either editable or read only. In some situations you may want the user to see the current value in Active Directory but not edit that value. Editable=“true” allows the field to be edited by the user while editable=“false” sets the field to read only.


Required Fields

You can set a field to be required by adding the required=“true” option to the field’s tag. Here is an example making the title required:

<field id="title" label="Title" attribute="title" visible="true" editable="true" type="dropdown" maxLength="64" required="true" />

Validation Format

Directory Manager allows you to define a rule set for field content using regular expressions (REGEXs). There are two parts to this process. You must first define the validation format (including the format name, example text, and the regular expression that will be used. This is done in the validations section of the DirectorySettings.xml file. Below is an example of a RegEx that requires that a user enter a phone number in either of these two formats: (808) 555-4321 or (808) 555-4000 x4322:

<validation format="US-Phone" formatExample="Example: (808) 123-4567 or 808-123-4567 x4321" 
regularExpression="((\(\d{3}\) ?)|(\d{3}-))\d{3}-\d{4}(( x)\d{1,5}| )?"/>

Once you have created a validation format, such as the one above called US-Phone, you then need to add the validationFormat=“US-Phone” option to the appropriate field. Below is an example of using that for the office phone number field.

<field id="officePhone" label="Office Phone" attribute="telephoneNumber" visible="true" editable="true" type="text" maxLength="64" 
validationFormat="US-Phone" />

Please note that our support personnel cannot assist you in creating custom regular expressions. We recommend you visit a site like htp://www.regexlib.com


Photos

Photo support has become one of our most popular features; this is because Microsoft is now displaying photos in Outlook 2010 and Lync clients if the photo is stored in the thumbnailPhoto attribute. Directory Manager can upload the photo to either the thumbnailPhoto or jpegPhoto attributes in Active Directory. Below is the recommended photo tag using the thumbnailPhoto attribute and a size of 128x128:

<photo label="Photo" attribute="thumbnailPhoto" visible="true" editable="true" width="128" height="128" quality="80" 
defaultValue="Images/noPhoto.jpg" />

When the photo tag's editable="true" option is set, the photo option appears in the General section of the user interface. When a user uploads a photo, the photo file is temporarily stored in the c:\inetpub\wwwroot\directorymanager\photos folder until the user saves their information. At that time, the photo is then stored in the Active Directory. Here is a fun tip, upload your photo, but don't save your information. Look in that folder on the IIS server to see how big the photo will be in the Active Directory.

Directory Manager - Luke Husky Photo

By default, the photos are stored in an attribute (thumbnailPhoto) as part of the user’s object in Active Directory. Regardless of the original photo file size, Directory Update “re-renders” the photo to the size specified in the DirectorySettings.xml file. Typical file sizes are between 5KB and 10KB. For more information, read our Photo Support TechNote.

Since we store the photo (by default) as a square image, we recommend the original source image also be square. Otherwise, the photo will look squashed or stretched.


Double Wide Fields

In some cases your data may not display properly when the field is half-width. If you want a field to be wider, add the doubleWide=“true” option to the field’s tag:

<field id="company" label="Company" attribute="company" visible="true" editable="true" type="dropdown" maxLength="64" doubleWide="true" />

Note in the screen shot below that the Company field is a double-wide field while the Office field is a single-width (default) field.

Directory Manager - Double wide field


Default Value

You can also specify a default value if the field type is a text box. This feature is only valuable if there is no data in the field to begin with.

<field id="title" label="Title" attribute="title" visible="true" editable="true" type="text" maxLength="64" defaultValue="Accountant" />

Multiline Fields

For most Active Directory data types, the multiline option is not very valuable, but for attributes like streetAddress or notes, it can be useful. Note that multi-line does not change how Active Directory stores the data, only how Directory Update displays it. Here is an example setting multiLine=“true” for the streetAddress field:

<field id="streetAddress" label="Street Address" attribute="streetAddress" visible="true" editable="true" type="text" maxLength="1024" 
multiLine="true" />

Directory Update - Multiline field


Help Notes and Example Text

Directory Manager is designed to help you provide as much help as necessary to the end user. This is in the form of a couple of different types of help fields. First, each "section" of the user interface, such as the General, Organization, Address, etc... Within each section, there is a note area at the bottom of the section. Below shows the Telephones section, the note tag is at the bottom of the image:

Directory Update - Telephone section and Notes field

This corresponds to the following section in the DirectorySettings.XML file. If you do not need the note, then save your self some screen space by setting the visible="false" option. Otherwise, you can customize the text to suit your organization's needs and best help your end users.

Directory Update - DirectorySettings.XML file Telephone Section

Each attribute can also have individual example text. This was originaly intended for phone number fields, but you can add the example option to any tag.

Directory Update - Field example text

The following is an example of adding the example option to the officePhone tag.

<field id="officePhone" label="Office Phone" attribute="telephoneNumber" visible="true" editable="true" type="text" maxLength="64" 
validationFormat="" example="Include your area code, such as: (212) 555-1234" />

Manager, Assistant, and Secretary Attributes

The Manager, Assistant, and Secretary attributes are special data fields that store object names. For example, in order to select a Manager, the manager must have a user name or contact name in the Active Directory already. These fields are not free-form text fields, but rather lookup fields for users and/or contacts. Active Directory Users and Computers only exposes the Manager attribute fog editing, but the Active Directory schema does provide for the Secretary and Assistant fields.

Directory Manager allows for one or more of these fields to be enabled. We provide a lookup box where the Directory Update can type in the first few characters of the person's display name.

Directory Update - Searching for a Manager

There is little-to-no configuration necessary to use these fields other than to enable them to be editable via the DirectorySettings.XML file.

<field id="manager" label="Manager" attribute="manager" visible="true" editable="true" type="lookup" />

There is one notable exception, though. If you have more than one domain in your forest, by default the lookup fields only query a single domain. Therefore you must enable global catalog lookups so that you can see the users from the other domains in your forest. This is done in the AppSettings.XML file. The useGlobalCatalog option within the lookupFields tag must be set to "true".

<lookupFields useGlobalCatalog="true" showOnlyExchangeEnabledUsers="false" showContacts="true" showDisabledUsers="false" maxResults="20"/>

Enabling Integrated Windows Authentication (Single Sign-on)

By default, Directory Manager uses a customizable logon form. However, a much more convenient way to use Directory Manager is to enable Integrated Windows Authentication (sometimes called single sign-on or Windows Login.)

Edit the Web.Config file and locate the <authentication mode=“Forms”> tag. You can find the Web.Config file in the root of the installation folder, by default that is in c:\inetpub\wwwroot\directorymanager. Replace mode=“Forms” with mode=“Windows”. That will enable Integrated Windows Authentication.

Directory Update - Enabling Integrated Windows Authentication

For more information, read our TechNote Enabling Integrated Windows Authentication.


Configuring the Search Interface

The search interface is broken in to 3 separate parts: the search interface, search results, and a tabbed view below the search results that represents the currently highlighed user. These are all controlled from the AppSettings.XML file.

Directory Manager - Interface components

One of the most common questions that we are asked is why are there only 100 search results generated and why is the listing not a true representation of the users in Active Directory. This is because we limit the maximum number of results to 100. We do allow you to narrow the search result so that only a subset of the objects in Active Directory are actually returned. The userList tag within the AppSettings.XML file allows you to control some of the search result listings including:

  • Maximum number of search results - maxResults
  • Results per page - pageSize
  • Column on which to sort the results - sortBy
  • Display only Exchange-enabled users - showOnlyExchangeEnabledUsers
  • Display disabled users (or not) - showDisabledUsers
  • Don't show an intitial search results screen upon connecting to the site - showInitialResults
  • Do or do not show the tabbed details pane below the search result - showDetailPane

Here is the tag that controls the above features of the Directory Manager search results feature:

<userList maxResults="100" pageSize="20" showContacts="true" showDisabledUsers="true" showOnlyExchangeEnabledUsers="false" showInitialResults="true" selectFirstRow="false" allowMultiColumnSorting="false" filterByColumn="true" showFilterMenu="true">

A fairly common question we are asked is if we can increase the maximum number of search results. Directory Manager uses LDAP to query the Active Directory and as such as designed as a "search" application more than a "browse" application. That being said, you can increase the maxium number of serach results by adjusting the maxResults option within the AppSettings.XML file. Note that Active Directory limits the maximum number of LDAP query results returned to 1,000 via the Active Directory parameter maxPageSize in the LDAP policy. This can be changed; see the KB article 315071: How to view and set LDAP policy in Active Directory by using Ntdsutil.exe.


Controlling the columns shown in the display and filtering attributes

For the search results grid, the AppSettings.XML file's columns sections allows control what the Directory Manager user sees. You can control the following:

  • Title for the column header - headerText
  • Show the attribute in column - visible
  • Include as a filter or search option - filter
  • Allow export to an Excel spreadsheet or text file

The attributes allowed in the search results grid should be used sparingly. Directory Manager auto-sizes the grid. You cannot manually specify individual column sizes. So if you have too many attributes the data will be compressed. We recommend no more than 5 or 6 columns be set to visible="true". The following is the first few lines from the AppSettings.XML file showing fields section:

<photo column="false" expandView="true" />
<field id="personalTitle" search="false" column="false" expandView="false" export="false" />
<field id="firstName" search="false" column="false" expandView="false" export="false" />
<field id="initials" search="false" column="false" expandView="false" export="false" />
<field id="middleName" search="false" column="false" expandView="false" export="false" />
<field id="lastName" search="false" column="false" expandView="false" export="false" />
...

Pre-filtering Search Results

By default, Directory Manager returns *all* user accounts found in the domain including service accounts, domain trust accounts, and other accounts. For your targeted user community, this may not be desirable.

We have created a document on the Documentation section of our Downloads page called "Applying Search Filters" that dicusses in more detail how to apply search filters, exclusions, and limit the search scope to a single parent organizational unit (OU).


Users and Contacts Display

By default, Directory Manager displays both users and contacts in the search results listing. An authorized user can edit the properties of either users or contacts.

Directory Manager - Display Users or Contacts

You can disable this feature or change the default behavior in the objectTypes section of the AppSettings.XML file.

<objectType text="Object Type" search="false" export="false">
<user text="User" />
<contact text="Contact" />
</objectTypes>

Exporting Search Results

The Export button on the Directory Manager interface gives you the ability to export the search results to an Excel spreadsheet or a common separated vault (CSV) file. This can disabled via the exports section of the AppSettings.XML file.

<exports enabled="true" text="Export" fileName="UserList">
  <excel text="Excel" visible="true" />
  <csv   text="CSV"   visible="true" />
  <pdf   text="PDF"   visible="false" />
</exports>