Planning a GALsync or contactSync Upgrade

Purpose

Upgrades of these products are not routine patching. Several releases changed things that break a working configuration if you are not expecting them, and in a partner arrangement an upgrade is a coordination exercise rather than a per-server task. This article covers what to check before, during and after.

The coordination constraint

Deal with this before anything technical, because it determines whether an upgrade can be done at all.

All partners in a synchronization scheme must run the same version. Synchronization between different GALsync versions is not supported. Data files carry the program version, and an environment below 8.2.0 cannot import current data files at all.

Separately, the matching conflict resolution that prevents attributes being written to the wrong object is only effective when every environment in the scheme is on 8.5.2 or later. One partner below that reintroduces the defect for everyone.

So in a multi-organization arrangement, the upgrade plan has to include partners you do not administer. Agree a window with them rather than upgrading your side and discovering the consequence.

What changed, by version

The changes most likely to break an existing configuration:

• 8.2.0 — data files carry the program version; environments below this cannot import current files.
• 8.5 — moves to the REST-based Exchange Online PowerShell V3 module. This is the point at which the older connection path stops working, which is why environments that "changed nothing" begin failing.
• 8.5.2 — matching conflict resolution, addressing attributes being written to the wrong object where one source object matches two target objects.
• 8.5.6 — the option to create a new user-based credential account is removed from the environment configuration.
• 8.6 — user-based authentication for Exchange Online is removed entirely. Certificate-based authentication through a registered application is the only supported method.
• 8.6.0 — Advanced PowerShell connection settings added to the Organization Settings dialog on the Exchange Online tab; national cloud parameters added for connecting mailboxes via Microsoft Graph; domains in an AD forest can be excluded from synchronization; the information bar indicates whether a policy is running.
• 8.7 — requires .NET Framework 4.8, Windows PowerShell 5.1 and ExchangeOnlineManagement module 3.10.1 or later. contactSync 8.7 adds Synchronize User Profile Photo for Exchange Online, requiring the ProfilePhoto.Read.All Graph permission; it measurably slows a policy run when enabled.

Earlier releases have their own version-gated notes; the Upgrade Instructions carry the full list and the Incompatibility chapter is the part to read rather than skim.

Before you upgrade

1. Read the Incompatibility chapter in the Upgrade Instructions for the span you are crossing — not just the target version.
2. Confirm partner versions and agree the order and window.
3. Check the platform prerequisites: .NET Framework, Windows PowerShell version, and the ExchangeOnlineManagement module version required by your target release.
4. Establish how you authenticate today. If any environment still uses user-based authentication, moving to certificate-based authentication is part of the upgrade, not a follow-up.
5. Back up. Export the configuration (Action → Export Configuration) and the status logs (Action → Export Status), and back up the program folder and the data folder under %ProgramData%.
6. Record your current object counts per policy. This is the single most useful number to have afterwards.

After you upgrade

1. Confirm the licence is activated, not merely installed. An unactivated licence cancels policies while everything else looks correct.
2. Check the environment configuration validates and that no policy carries a red X.
3. Install or update the ExchangeOnlineManagement module for all users, not just your own profile — scheduled policies run as the service account.

   Install-Module ExchangeOnlineManagement -Force -Scope AllUsers
   Get-Module -ListAvailable ExchangeOnlineManagement | Select-Object Name, Version, ModuleBase

4. Run one export manually and compare the object count against the figure you recorded beforehand. Do this before letting the import run.
5. Confirm the export safety limits are still set — Minimum objects to transfer data file and Maximum errors to transfer data file. These are what stop a post-upgrade export anomaly from deleting contacts at the target.
6. Run the import and verify a sample of contacts, including one you know changed recently.
7. Check the match counters in the log summary. An unexpected distribution across match combinations after an upgrade is worth understanding before it becomes a data problem.

Upgrades do not fix everything, and can surface new symptoms

Two honest cautions, because both have happened:

An upgrade does not repair damage already done. Where objects have been corrupted by a defect that a later version prevents, the prevention applies going forward; existing objects may still need manual repair. See GALsync Writes a Contact's Attributes onto the Wrong Object.

An upgrade can change what a policy considers in scope. If contacts stop updating after an upgrade or reconfiguration — reported as up to date, no errors, but frozen — the source domain recorded on existing contacts may no longer match the synchronization. See Synced Contacts Report Up to Date but Never Change: the Source Domain Problem.

Neither means the upgrade was wrong. Both mean the verification steps above are worth doing properly rather than assuming a clean run is a clean result.

If something breaks that worked before

Collect Action → Export Configuration and Action → Export Status from both servers, confirm the newest log covers the failing run, and state plainly which version you came from and which you went to. The version span is the most useful single fact for anyone diagnosing a post-upgrade failure, and it is frequently the one missing.

References

• GALsync 8.7 Upgrade Instructions p.10 and contactSync 8.7 Upgrade Instructions p.4 — version-by-version incompatibility notes and platform prerequisites.
• contactSync 8.7 Manual p.153 — Synchronize User Profile Photo and its Graph permission requirement.
• GALsync 8.7 Manual p.74 — program and data folder locations for backup.
• GALsync 8.7 Manual p.167 — export safety limits.
• The current manuals, upgrade instructions and version history are published by NETsec at netsec.de.