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 Upgrade from Previous UnitySync Version.

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 minor version from the current release may require special care. Please contact support@dirwiz.com with any questions or concerns.

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

2. Disable any tasks used to automatically execute scripts for your current UnitySync connections. Note, Below, refer to #13 “Update your scripts” for required changes to the shell.exe syntax used in your scripts).

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

4. 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 insure the underlying directory structure is updated properly.

5. Move your existing connection data and custom configuration files to the new location:

   • 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.

6. 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. UnitySync v2.3 and newer uses javascript rather than perl, and failure to upgrade your perl-scripted mappings to javascript could result in mass modifications and incorrect attribute data.
   • To find instances of perl scripting, use findstr as outlined in this knowledge base article.
   • If you are using eval.pl or any perl scripting, contact our Technical Support Team for assistance before proceeding with your upgrade.
   • If you do not have an existing eval.pl file, and do not find any instances of perl scripting via findstr, proceed to next step.

7. 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.

8. 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.

9. Determine if any of your connections use filters on an Office 365 (O365) Source

   • Are you discovering from any O365 tenant? If not, proceed to next step.

   • Does the Source tab of your o365 Source connection(s) use an Optional Query Filter? 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.

10. Determine if you have any Join ONLY connections. (Destination 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.

11. 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.

12. 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

13. 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.

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

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

16. 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