Upgrade from OLD UnitySync Versions PRIOR to v3

This article relates to Upgrades when the current UnitySync version is OLDER than UnitySync v3.0.

If your current version is v3 or newer, refer to UnitySync Upgrade Notes and Requirements.

If you are running v3 or older, please proceed…

IMPORTANT NOTE: It is essential that you review and complete all of the upgrade steps before you start running any connections. Failure to do so could result in mass modifications, mass deletes, or incorrect or blank Destination attribute data. Upgrading from versions more than one major version from the current release will require special care. Please contact support@dirwiz.com with any questions or concerns.

Upgrade steps

1. Before you start your upgrade, please review the System Requirements for UnitySync.

2. Back up your current installation by zipping the entire install directory and saving to a new location.

3. Disable any tasks used to automatically execute scripts for your current UnitySync connections.

4. Download the latest software at dirwiz.com/download.

5. Execute the UnitySync install program and follow the prompts for installation. The default installation directory is C:\UnitySync-v# (where # refers to the current version number), but you may install to any directory name provided the underlying directory structure names remain as installed.

   IMPORTANT NOTE: Please DO NOT install directly over your previous version. A fresh installation is required to ensure the underlying directory structure is updated properly.

6. Copy your existing UnitySync data to the new install:

   • copy the \connections directory
   • copy the \global\map\custom directory
   • copy the \global\sourcedef\custom directory
   • copy the \global\smtp.txt
   • copy the \global\eval.js (if applicable)

     IMPORTANT NOTE: It is not necessary to move your \key.txt file as you will need to request a new permanent key once your upgrade is complete. More information regarding updating your key is available below.

Verify if any custom settings require special attention for this upgrade:

Tip: If you have only 3 or 4 connections, it may just be easier to look at each connection and object map file (if the connection uses one) in the UI. Reviewing each connection this way you can skip the findstr methods.

1. Determine if you are using any perl scripting in your custom map files.

   • If you have an eval.pl or perl scripting in your custom map files, and you are upgrading from v2.3 or older, it is critical that you make certain changes before running connections in your upgraded installation. As of UnitySync v2.3, UnitySync utilizes javascript rather than perl. Failure to upgrade your perl-scripted mappings to javascript could result in incorrect attribute data.

   • To find instances of perl scripting, use findstr as outlined in this knowledge base article. Use findstr to search for instances of the & character in \global\map\custom. For example the map file may contain a mapping similar to the following:

     displayname#256=&formatDisplayName()&

   • If you find custom map files containing any perl scripting, contact our Technical Support Team for assistance before proceeding with your upgrade.

   • If you do not find any instances of perl scripting, proceed to next step.

2. Determine if you have any CSV or ODBC Source connections that need updating.

   • If you have any connections using CSV or ODBC as a Source and upgrading from v2.4 or older, it is critical that you review field definitions and custom object maps to ensure only alphanumeric characters or a dash are used. Any other characters may cause mass modifications and blank attribute values.

   • To find out if you have any CSV or ODBC Source connections, use findstr as outlined in this knowledge base article to search for csv- or odbc-.

   • If you find any CSV or ODBC Source connections, please refer to this knowledge base article to update field definitions and custom map files.

   • If you do not find any CSV or ODBC Source connections, proceed to the next step.

3. Determine if you have added a custom mapping for unicodepw in any of your connections, per this knowledge base article.

   • As of v2.7, unicodepw has been removed from no-mod-attribs. Behavior previous to v2.7 was that unicodepw would be set on creation of an object, but then not modified on subsequent syncs. As of v2.7, if mapped, unicodepw will modify on each sync.

   • To find out if you have unicodepw mapped in any of your connections, use findstr as outlined in per this knowledge base article.

   • If you find that you are mapping unicodepw, it is unlikely you want to apply changes to password on future syncs. Therefore, a change is required for this connection. Please contact our Technical Support Team for assistance with your particular situation.

4. Do any of your connections use o365? If not, skip to next step.

   • If your connection uses a Source of o365, does the Source tab of your o365 Source connection(s) use an Optional Query Filter? If no, skip to the next step.

     If yes, are you upgrading from a version older than v2.8? If Yes, please review Filters: Office 365 (O365) Discovery which outlines the changes to O365 filters since v2.8. Adjust your queries as needed.

   • Does the Source tab of your o365 Source connection(s) use an Optional Query Filter on windowsemailaddres such as (windowsemailaddress=*)?

     If yes, edit the filter to use primarysmtpaddress instead. (The latest EXO version does not return windowsemailaddress).

ALSO Important: Edit your custom map files to use ^primarysmtpaddress^ instead of ^windowsemailaddress^.

• Does the Source tab of your o365 Source connection(s) allow discovery of hidden o365 objects? In previous version, UnitySync Discovered ALL objects from the O365 Sources. In order to avoid discovering hidden objects, a source tab query was required to filter them out. (HiddenFromAddressListEnabled=FALSE).

  • If your source tab includes (HiddenFromAddressListEnabled=FALSE), the filter can be removed. The new Hidden check box (left unchecked) replaces the need to use the HiddenFromAddressListEnabled filter.

  • If your source tab does not include (HiddenFromAddressListEnabled=FALSE), then your connection has been syncing hidden objects, you can check ‘Hidden’ to continue to do so.

  • Please contact our Technical Support Team if you need assistance crafting your queries.

5 . Determine if you have any Join ONLY connections. (Destination tab Sync/Join Mode set to Join, not Create or Both).

You can tell if there is a custom object map by looking at the Custom tab - if there is a file selected in the Object Map field, you are using a custom object map.

• If your Join ONLY connection uses the default map file, proceed to the next step.

  • If your Join ONLY connection does have a custom file defined, click Object Map to edit the file.
    • The first line of the map file should have a DN mapping.
    • If the first line contains DN= this is the DN mapping, you can proceed to the next step.
    • If there is no DN mapping, you must add one to avoid sync errors. We advise using the following DN mapping: dn=cn=~mail~,~struct~
      NOTE: Adding the DN mapping in a JOIN only connection will NOT cause the DNs of your destination objects to change.

6 . Determine if you have any CREATE ONLY connections. (Destination tab Sync/Join Mode set to Create, not Join or Both). We recommend you enable ‘Both’ and use the filter suggested in the Dest tab article.

Once you’ve completed the above connection changes, there are steps to update your IIS virtual directory, sync scripts as well as run Disc/Simulation to verify results prior to running Sync.

1. Update your web server virtual directory, if applicable. Please refer to Web Server Configuration to remind yourself of the steps for web server configuration, and update your virtual directory to the new location where applicable.

2. Test your connections in the new installation. We recommend a complete lab environment where possible, to ensure all changes, including upgrades, are thoroughly tested outside of production. There are ways you can test changes and upgrades within a production environment, however:

   • Using Discovery and Simulation to test changes
   • Test Changes against a Single Object

3. Update your scripts:
   As of v4.6, there is a change to the syntax for calling shell.exe in your automated scripts. The syntax should now include option --conn prior to the connection name.
   i.e
   shell.exe --conn “IN\Paris-to-Master”

   Refer to Automating your UnitySync Connections for details.

4. Re-enable your scheduled tasks, if applicable.

5. Request a new key. Send your new Serial Number to keys@dirwiz.com and we will provide an updated license key.

6. Retire your previous version. Not only does it violate your license agreement to use more instances of the software then you are licensed for, it also could cause issues with your sync. Repeatedly switching between original server and the new server causes discrepancies between the Source and the hash tables that shows up in the log file. We advise that you do not return to your previous version after you have successfully synced from your upgraded, reinstalled or moved instance.

#Ref: 3207 Post v3