DirWiz Logo

Article Tags

Upgrade from Previous UnitySync Version

2021-02-25 15:28:28

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

    IMPORTANT NOTE: Since UnitySync has been Discovering ALL objects on O365 Sources to date, if you were not previously filtering Hidden objects as described below, you may see a number of items flagged for Deletion when you run Simulation in step 11. If you are concerned by this, check Hidden on the Source tab to continue syncing ALL of the objects returned from the O365 Source Discovery. If you do not want to sync Hidden objects, leave this unchecked but be aware that choosing to stop syncing Hidden objects now will result in the deletes shown in your Simulation.

    • Are you syncing from any O365 tenant? If no, proceed to step 10.
    • If yes, view the Source tab of the connection(s) in question. Do you have anything configured in the Optional - Filter section? If no, proceed to step 10.
    • If yes:
      • See note above for a caution which may result in unexpected deletion of synced objects.
      • By default, O365 Discovery returns all objects whether they are hidden or not. You may have applied the filter HiddenFromAddressListEnabled=FALSE in order to pull ONLY objects that are NOT hidden. You can now remove this filter and simply leave the new Hidden option unselected on your Source tab.
    • Please also review the following knowledge base article which outlines the changes to O365 filters in v2.8 and later versions, and adjust your queries as needed.
  10. 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.
  11. 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:
  12. Update your scripts and re-enable your scheduled tasks, if applicable. See Automating your UnitySync Connections to refresh your memory, as there may have been changes to the procedure.
  13. Request a new key. Send your new Serial Number to keys@dirwiz.com and we will provide an updated license key.
  14. 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.
Share this article: Twitter reddit