Category:SimpleSync
Last Updated:2011-08-03
Active Directory
SimpleSync v3.x is no longer a supported version.
In order to upgrade, you must have a current maintenance agreement.
Licensing Considerations when upgrading from any 3.x version
If you are currently running a pre 3.4 version of SimpleSync, you WILL need a new license key. Contact support@dirwiz.com to request a new license key.
If you have let your maintenance contract lapse, you can renew your contract, and bring it up to date. When you contact sales@dirwiz.com you will be offered the opportunity to renew your maintenance contract and receive new license key.
**********************************************************
** Do NOT install the latest version directly over any 3.x version of SimpleSync.
**********************************************************
1. Click Help About in your exiting version of SimpleSync to determine the SimpleSync version you are currently running. See Licensing Considerations above to determine if you need a new license key.
2. Download the latest version of SimpleSync from http://www.dirwiz.com/simplesync/download
3. RENAME your current \SimpleSync-v3 directory. (This is to ensure you do not inadvertanly allow your existing batch scripts to execute this now obsolete version of SimpleSync. When you have completed
this Upgrade process, you can zip and archive the old SimpleSync directory.)
4. Execute the install program and follow prompts for installation. The default installation directory is C:\SimpleSync-v5. (Do not install over your existing SimpleSync version.)
**Copy Connections, Custom Map Files, Custom Sourcedef files, and License Key.
5. The new software is now installed. Before starting simpleSync v5, copy Connections, custom files from the previous version's installation directory.
Copy the \connections directory from your prior installation into the new one
i.e. c:\SimpleSync-v5\connections
Copy all custom files from your prior installation directory into the new one
i.e c:\SimpleSync-v5\global\map\custom
i.e. c:\SimpleSync-v5\global\sourcedef\custom
6. If upgrading from v3.x: Custom Sourcedef files are supported in this latest version.
If you have made changes to your *default* Source Definition files (in \Global\Sourcedef) at any time under the previous version, you must use the Custom Mapping option to create a custom Sourcedef for all affected connections. For example, if you changed ActiveDir.txt, then affected connections will be all those that use an ActiveDirectory (including Ex2000/2003) directory type as the Source. If appropriate, you may create a single custom ActiveDir sourcedef and use it for all connections using an ActiveDir/Ex2000/2003 source directory type. Each connection with an ActiveDir source must be configured to point to this custom ActiveDir sourcedef file. Contact Support@dirwiz.com if you need assistance.
**** Upgrade your existing connections
7. Run the SimpleSync v5 Admin tool
The following steps 8 - 11 are required in order to upgrade each individual connection configuration to the latest format. Perform these steps on every connection in the v5 GUI.
8. Select a connection
9. You will be prompted to verify the Map Template and Sync Engine for the Source and Destination directories. The default choice is usually the correct one. If for some reason, your connection can not be converted, a popup message will indicate this. Then, you will be prompted to enter the correct
Map Template and Sync Engine for this connection. Contact Support@dirwiz.com if you need assistance.
10. On the General tab of the connection, enter a brief description of the connection (enter anything, this will help ensure the changes are applied.)
12. Click the Destination tab. This updates the connection with new Create/Join options.
13. Click Apply.
You should have received a license key string with your software download. Go to v5 Help About and insert this key string, then click Save Key.
*IMPORTANT: Once you have completed the connection upgrade procedure for all connections, review the below note regarding connections that sync to a CSV destination. If you have any connections that export to CSV, you must convert your CSV map files prior to running these connections under SimpleSync v5.
14. This step only applies when upgrading from 3.4.3 or 3.4.3 SP1.
(If you are upgrading from a pre-3.4.3 version or 3.4.3 SP2, you can skip this step.)
There is a Special Consideration for connections with an Ex2000/2003 destination, that is utilizing *default mapping*. The following two mappings have been removed from default mapping in this release. These mappings were found to be problematic in most cases, so they have been removed from the default
map files. If you have previously implemented connections to an Ex2000/2003 destination and are successfully utilizing these via default mapping, you will need to reapply these mappings through the use of a Custom Map file. If you have questions regarding this default mapping change, contact Support for more information.
legacyexchangedn=~x500~
proxyaddresses=X500:~x500~
If you are uncertain if you need to do this, contact Support@dirwiz.com to review a high level log file and your default or custom map files.
**** Review Custom Map files for required changes due to Literal Mapping changes
In the next two steps, review all Custom Map Files to confirm if modifications are needed. In EVERY connection, go to the Custom Map tab. If an Object Map file exists, click EDIT to view it. Then perform steps 15 and 16 to confirm if any changes are required
15. Previous versions of SimpleSync used special character sequences to map reserved characters
i.e. ~ ( { [ etc
If you are using custom mapping that utilizes these Literal Character Mappings (LCM), these mappings must be modified to use the New Literal Character Mapping style (NLCM) as shown below.
The old style mapping of these literals looked like this:
(LCM) (literal)
&rb represents ]
&lb represents [
&rs represents }
&ls represents {
&rp represents )
&lp represents (
&t represents ~
&h represents ^
&p represents #
&c represents %
As of v4, the mapping of these literals is done by escaping the desired characater with a preceding \ character
(NLCM) (literal)
\] represents ]
\[ represents [
\} represents }
\{ represents {
\~ represents ~
\^ represents ^
\# represents #
\% represents %
For example, all istances of &rb must be changed to \]... all instances of &t must be changed to \~ etc.
Note: Parens '(' and ')' are not reserved and therefor do not need to be escaped. Change any instance of &rp or &lp to the lone charactesr, ( and ).
16. Custom Map files using embedded perl scripts must escape the ? character in the scripting
In any custom mapping perl scripting, escape the ? character with a \
i.e. \?
**** Simulate and then Run your Syncs
17. On the General tab, disable Sync, enable Discovery and Simulation. Review the results of the Simulation before running a Sync. Note: The first Sim will show Adds for all objects. As long as the DN matches the previously synced contacts, when a real sync runs, a Link will be performed. If you have any questions about Sim results, contact Support before running a Sync.
18. Synchronize (run) each of your connections twice. This will rebuild the SimpleSync data files and ensure your directory is being updated properly. NOTE: You must run your connections twice NOW, before
making any changes to connection configuration under this upgraded installation.
**** Update your automated batch scripts
19. The command lines to run your connections via a batch script havechanged. Every connection is now run by execution of the same program, Shell.exe.
i.e. Shell "Connection Name"
You MUST update your batch scripts to call this new executable to kick off your SimpleSync connections. Refer to the Scheduling topic of the SimpleSync v5 Help file for more information.
Your upgrade is now complete.
The below information relates to Connections that output to CSV.
All v3 connections with a CSV output file as a destination will require additional configuration before they can be run under v5.0.
Select the connection to convert. When prompted, select CSV as the destination Sync Engine. Select a destination Map Template on which to base your mapping. (This is just a base, customizations will be required.) When you click OK, you will receive a message indicating CSV processing has changed. Below are the instructions on how to generate a new custom mapping file for your connection.
Previous versions of SimpleSync used two files to define the CSV output structure. A -header.txt was used to define the header line of your csv file. A -person.txt was used to define the data lines of your csv file. As of version 4.0, a single -person.txt map file is used with your CSV output connection. The process to convert your -person.txt file to the new csv mapping format is outlined below.
1) On the Destination tab of your connection, fill in the parameters as instructed in the Text Output topic of the SimpleSync 4.0 help file (click Help on the destination tab).
2) Your custom map files should have been copied over during the upgrade process (step 6 above). From File Explorer, open the -header.txt file from the old connection (for reference only, this file is now obsolete).
3) On the Custom Map tab, click Edit Object Map to open the original -person.txt file. Using the old -header.txt as a reference, modify the -person.txt file to use the new mapping format. (If you are familiar with standard ldap-ldap mapping syntax, you will notice, this format is now identical to the standard ldap-ldap map file format.)
The format of the new -person.txt file is: Column Header=^Source Attribute^
Example of old style -header.txt for CSV connection
EmployeeID, First Name, Last Name, Mail, Street, City, State, Zip,