Upgrade from Previous UnitySync VersionCreated: 2019-08-19 13:22:08
Modified: 2023-12-08 17:17:52
Tags: System Requirements UnitySync UnitySync Release Notes Install Guide
This article relates to Upgrades if your current UnitySync version is v3.0 or newer.
If your current version is older than v3, refer to Upgrades when the current UnitySync version is OLDER than UnitySync v3.0.
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 firstname.lastname@example.org with any questions or concerns.
Back up your current installation by zipping the entire install directory and saving to a new location.
Disable any tasks used to automatically execute scripts for your current UnitySync connections. (Note, refer to #10 below for required changes to the shell.exe syntax used in your scripts).
Download the latest software at dirwiz.com/download.
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.
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.
Determine if any of your Source o365 connections have a Source tab filter using windowsemailaddress.
Such as: (windowsemailaddress=*)
If yes, modify the filter to use primarysmtpaddress instead.
(Why? The latest EXO version does not support discovery of windowsemailaddress).
ALSO, Edit your custom map files to use ^primarysmtpaddress^ instead of ^windowsemailaddress^.
Such as, change:
Please contact our Technical Support Team if you need assistance crafting your queries.
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.
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.
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:
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.
shell.exe --conn “IN\Paris-to-Master”
Refer to Automating your UnitySync Connections for details.
Re-enable your scheduled tasks, if applicable.
Request a new key. Send your new Serial Number to email@example.com and we will provide an updated license key.
- 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.