Customizing Directory Update

Directory Update 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 a few 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 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, enabling the Password Management tab, and filtering options for lookup boxes like the Manager box.

  • 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 and screen colors. 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 the field’s screen label
  • Set the field type
  • 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>
</field>

This "tag" produces a field on the Directory Update 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 Update 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 Update 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\directoryupdate\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 Update - 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 Update - 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" />

Multi-line Fields

For most Active Directory data types, the multi-line 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 Update 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 originally 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 Update 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 Windows Login (Single Sign-on)

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

Edit the Web.Config file and locate the <authentication mode=“Forms”> tag. You can find the Web.Config file in the root of the installatoin folder, by default that is in c:\inetpub\wwwroot\directoryupdate. 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.