Upgrading from Previous Versions to V3.0 and Later

Customers whose support and maintenance is up-to-date are eligible to upgrade from an older version of the software to a newer versions. However, during the installation process the installer programs for Directory Update, Directory Manager, Directory Search, and Directory Password do not provide a direct upgrade path from older versions.

This article applies to:

  • Directory Update v3.0
  • Directory Manager v3.0
  • Directory Search v3.0
  • Directory Password v3.0

Almost all configuration and customization work is performed via XML files. The v3.x product family made substantial changes to some of these files. We provide an XML updater but if your current version of the software is more than one or two versions behind, the converter utility may not be able to update the files. In that case, you will need to re-customize your XML files using the new XML files as your template.

License Keys

Updating to a newer version usually requires a new license key. Contact support @ ithicos.com to determine if you are eligible for updates.

XML Changes From Previous Versions

In the v3.x versions of our products, we made a couple of significant changes to the DirectorySettings.XML file. Below is an example of the Office name attribute from earlier versions:

<office label="Office" type="dropdown" visible="true" editable="true">
  <value>Office 1</value>
  <value>Office 2</value>
</office>	

Now, let's take a look at the new Office attribute. The open and close text is no longer the field name, but the world field. Next is the id property; this is required and used internally by our software. The field id is used in the AppSettings.XML, SubSettings.XML, and AddressSettings.XML files. The value are using is the same as the field name in previous versions. Do not change or localize the id value. Next is the attribute property; this maps to the LDAP attribute name for this field in the Active Directory. Finally, the maxLength property specifies the maximum number of characters that the Active Directory attribute can hold.

<field id="office" label="Office" attribute="physicalDeliveryOfficename" visible="true" editable="true" type="dropdown" maxLength="128">
      <value>Office 1</value>
      <value>Office 2</value>
</field>	

For Directory Manager and Directory Update, you can retain these files

  • AddressSettings.XML
  • Subsettings.XML

You can not retain older versions of the DirectorySettings.XML, AppSettings.XML, or PasswordSettings.XML files nor can you retain the dll, css, ascx, or aspx files. You must use the new versions of these files or use the XML converter.

The most common support problem we see from customers during upgrades is that they accidentally keep older versions of the files that they should not have retained.

Update / Upgrade Process

The upgrade from an older version to a newer version is essentially an uninstall and reinstall. The following is an example for upgrading Directory Update (v2.6 and later), but these steps can be used for Directory Manager v2.3.

  1. Backup the c:\inetpub\wwwroot\DirectoryUpdate folder
  2. In Control Panel, remove Directory Update
  3. Delete the c:\inetpub\wwwroot\DirectoryUpdate folder
  4. Follow the instructions to install the new version
  5. Test the new installation with the default files
  6. Make a backup copy of the .\Settings folder so that you have a copy of the default XML files
  7. Make an additional backup of the default XML files so that you have the original files
  8. Run the .\Configuration\SettingsUpdater.exe and update your old AppSettings.XML and DirectorySettings.XML files
  9. Test using your converted XML files
  10. Copy your original SubSettings.XML and AddressSettings.XML files in to the .\Settings folder
  11. Test using the updated and restored XML file

You may have noticed a theme in those steps. Each step of the way, test your update to ensure that the software is still working. This will save you some time trying to figure out where to start solving an update problem.

If you run in to problems during the installation, we have troubleshooting guides for each supported operating system on the TechNotes Support page.

XML Settings Updater

We have introduced a new utility called Settings Updater. It reads your old DirectorySettings.XML and AppSettings.XML files and moves your original configuration settings to the new XML files. This utility works best when converting from Directory Update v2.6 / v2.7 and Directory Manager v2.3 / v2.4. It may not work with older versions. The Settings Updater is found in the .\Configuration folder and is named SettingsUpdater.exe. Here is an example of how to update the DirectorySettings.XML file:

  1. Copy the .\Settings from your older version to a folder such as c:\temp
  2. In the .\Configuration folder, run SettingsUpdater.exe. (Note, you may need run it by SHIFT-Right Click and choosing "Run As Administrator.")
  3. In the drop-down lists, select the application and which file you are updating. In the Source File box, browse and select your original XML file. In the Destination File box, browse and select the XML file that comes with the new version.
  4. Click the Update button to update the file
  5. Updating an XML file with Settings Updater
  6. The update should not take more than a few seconds. It will make a backup copy of the target XML file before updating it.
  7. Repeat the process for the AppSettings.XML file

The Settings Updater may not work in the following situations:

  • The XML files are from an older version of Directory Update (2.5 or earlier) or Directory Manager (v2.2 and earlier)
  • Attributes have been moved around or new attributes have been added

Upgrading from Older Versions

The XML files from older versions of Directory Update (v2.5 and earlier) and Directory Manager v1.6 and earlier are not compatible with newer versions of Directory Update. You must completely remove the old version and customize the XML files that come with the new version.

  1. Backup the c:\inetpub\wwwroot\DirectoryUpdate folder
  2. In Control Panel, remove Directory Update
  3. Delete the c:\inetpub\wwwroot\DirectoryUpdate folder
  4. Follow the instructions to install the new version
  5. Create a dedicated application pool for Ithicos Applications (such as IthicosAppPool)
  6. Test the new installation with the default files
  7. Make a backup of the default XML files so that you have the original files
  8. Customize the XML files that come with the new version. You can use your old XML file as a guide.
  9. Test during the customization.
Last Review: 6 April 2018