How to Prevent GALsync Contact Deletion During Export Errors

Purpose

GALsync matches synchronized objects by primary SMTP address. If an export produces an incomplete or error-laden data file, the following import cannot match the contacts it already created, treats them as gone from the source, and deletes them. A later, complete export recreates them — often hours or days later, after users have already noticed. This article explains why that happens and how to stop the incomplete file from ever reaching the import.

Understanding contact deletion scenarios

GALsync deletes a contact in the target environment when it cannot find that contact in the data file it is importing. That is by design: it is how a user removed at the source stops appearing in the partner's address list. The failure mode is that an export which partially succeeds looks identical, to the import, to a source in which those objects were genuinely deleted.

Two situations produce this:

• An incomplete export. A network interruption, an unavailable domain controller, a PowerShell session that drops mid-run, or throttling on the Exchange Online side can all end an export early. The file is valid; it simply contains fewer objects than it should.
• An export where objects are written without a primary SMTP address. Because the primary SMTP address is the matching key, an object exported without one cannot be matched on import. Log entries reading Missing email address against a large number of objects are the signature of this.

There is also a third cause that is not an export fault at all. Two import policies writing into the same organizational unit will delete each other's objects. NETsec documents this explicitly: if policy 1 imports users A and B, and policy 2 then imports users A and C into the same OU, user B is removed when policy 2 runs. The same applies to two export policies targeting the same Exchange Online organization. If deletions recur on a predictable cycle rather than after a visible error, check for overlapping policies before investigating the export.

Identifying export job errors

Work from the export side first, because the import is only doing what the file tells it to.

1. In GALsync, use Action → Export Status on the exporting server to collect the log files, and Action → Export Configuration to capture the policy settings. Do the same on the importing server — a deletion event is only fully explicable with both sides.
2. In the export log, count the objects written and compare that against the number you expect. A file that is short by a meaningful margin is the cause, whatever else the log says.
3. Search the export log for Missing email address. If it appears against most or all objects, the export ran to completion but produced a file that cannot be matched, which is more dangerous than an export that failed outright.
4. Check whether the export finished at all or was still running when the import began. Jobs that hang and require a service restart to complete are a known cause of a partial file being consumed.

Configuring deletion prevention

The controls that prevent this are on the export policy, not the import policy. Both are in Directory Settings of the export policy, and they work by refusing to send a data file that fails a sanity check — so the import never sees a file it would act destructively on.

Minimum objects to transfer data file. Sets the smallest number of objects the file must contain before GALsync will send it. If the export produces fewer, the file is not transferred. NETsec's own worked example is exactly this failure: if you expect to export over 11,000 objects, set the minimum to 11,000; if a network error means only 8,000 are found, the file is held back, and without that limit "in the target environment the missing number of contacts would have been deleted even though they still exist in the source."

Maximum errors to transfer data file. Sets how many errors GALsync will tolerate while building the data file before it refuses to send it. If the limit is exceeded, the file is not transferred to the target.

Set both on every export policy. Choose the minimum from your actual object count with a small allowance for normal churn — a figure a few per cent below the current count is usually right, and one set too close to the true number will hold back legitimate exports after a round of leavers.

Also confirm the one-policy-per-OU rule. One import policy should write to exactly one organizational unit, and only one export policy should target a given Exchange Online organization from the same source. This is the single most common configuration cause of deletions that no export setting will prevent.

Scheduling and throttling

Exports that run very frequently are more likely to be caught by Exchange Online throttling, and a throttled export is more likely to produce a partial file. Where a synchronization interval of a few hours has been configured, consider whether a single daily run meets the requirement — address list data rarely changes fast enough to justify more, and each additional run is another opportunity to ship an incomplete file.

Version matters here too. Exports that hang and require a restart of the GALsync service to complete, and exports that write objects without their primary SMTP address, have both been addressed in maintenance releases of the 8.6 series. If either symptom is present, confirm the installed version before changing configuration; the current release is the first thing to rule out.

Monitoring sync operations

• Enable global logging from Action → Global Logging so that policy runs are recorded consistently rather than only when something fails.
• Check the information bar at the bottom of the GALsync window to confirm whether policies are running as scheduled.
• Watch the object count in successive export files rather than only the success or failure of the job. A steady count that suddenly drops is the earliest warning available, and it appears before any contact is deleted.
• After any GALsync upgrade, compare the first export's object count against the last export from the previous version before allowing the import to run.

Recovering from a mass deletion

1. Stop the schedule. Disable the affected import policy before doing anything else, so that a subsequent run does not compound the problem.
2. Do not delete the target objects. They may be recreated automatically by the next complete export and import cycle.
3. Fix the export first. Establish why the file was short or unmatched, correct it, and confirm a complete file is produced before re-enabling the import.
4. Apply the minimum-object and maximum-error limits before re-enabling, so the same partial file cannot be consumed a second time.
5. Expect Outlook cache effects. Contacts that are deleted and recreated receive a new legacyExchangeDN. Users replying from cached Outlook entries or autocomplete will receive non-delivery reports until the cache refreshes, even after the contacts are back. See the article on primary SMTP address changes for the mechanism and for how to avoid it when a change is planned.

References

• GALsync 8.7 Manual p.167 — Minimum objects to transfer data file and Maximum errors to transfer data file.
• GALsync 8.7 Manual p.12 — one import policy per organizational unit; one export policy per Exchange Online target.
• The current GALsync manual and release notes are published by NETsec at netsec.de.