GFI ARCHIVER AI · MIGRATION GUIDE
Migrating from EWS to Microsoft Graph
Move Exchange Online journal archiving to Microsoft Graph without moving a single message of historical archive data. Five steps, one maintenance window, full rollback path.
- Applies to 15.14 and later
- Complete before October 2026
- Exchange Online only
EWS RETIREMENT TIMELINE
Upgrade to 15.14, register the Graph application and switch your journal sources.
Microsoft begins blocking EWS for Exchange Online tenants. Rollback then needs Microsoft’s temporary opt-out.
EWS is removed permanently. The opt-out ends.
Exchange Server on-premises is not affected by this retirement.
ON THIS PAGE
Guide last reviewed September 17, 2026 for GFI Archiver AI 15.14.
OVERVIEW
What this migration does, and what it leaves alone
Microsoft retires Exchange Web Services in Exchange Online in phases from October 1, 2026 and removes it on April 1, 2027. GFI Archiver AI 15.14 adds Microsoft Graph as the supported replacement for reading your journal mailbox. Only the retrieval method changes.
- Every message already in your archive
- Exchange Online journaling rules
- The journal mailbox itself
- Archive stores, retention and search
- New journal messages are retrieved over Microsoft Graph
- A new mail server source is added with the
-Graphsuffix - The matching EWS source is deactivated automatically
- Archived messages move to the journal mailbox’s Deleted Items
An existing EWS source is never converted by editing it. You add a new Graph source instead. When you save it, the EWS source for the same journal mailbox and folder is deactivated automatically and the wizard’s last page names it. Keep that EWS entry until you have verified Graph archiving, then delete it. Each source removes a message from the journal mailbox after archiving it, so a pre-upgrade configuration where both are active can archive the same message twice. The Dashboard warns about it.
No data migration
Historical archive data is not moved, re-indexed or re-imported. Nothing already archived is removed.
One maintenance window
Upgrade, register the application, add the Graph source and verify. Folder Structure Retrieval can follow later.
Reversible
Deactivate Graph, activate EWS. Rollback works for as long as EWS still works in your tenant.
BEFORE YOU START
Prerequisites
Work through this list before you open the installer. Tick items off as you confirm them.
- The GFI Archiver AI installer for a release with Microsoft Graph support (15.14 or later).
- GFI Archiver AI administrator access.
- Microsoft Entra ID permissions to register an application and grant admin consent. Global Administrator or Application Administrator is usually required.
- Exchange Online administrator access, if you plan to restrict the application to selected mailboxes with Exchange RBAC for Applications.
- A scheduled maintenance window and a confirmed backup of the GFI Archiver AI configuration and databases.
- No pending Windows restart. Restart the server first, otherwise the upgrade can fail to stop the GFI Archiver AI services and roll back.
- Microsoft .NET Framework 4.8 on the GFI Archiver AI server. 15.14 is the first release that requires it; without it the installer lists it as a missing requirement and stops.
- Outbound HTTPS from the GFI Archiver AI server to Microsoft Graph and Microsoft Entra ID.
- A supported operating system – see the System Requirements for GFI Archiver AI.
- Windows PowerShell 5.1 or later to run the application registration script.
Record your current EWS source configuration
Write these down before upgrading. You need them to rebuild the same source over Graph, and to roll back cleanly.
1. Source name
And the server or node where it runs.
2. Journal mailbox
The exact SMTP address.
3. Mailbox folder
Usually Inbox. Use the English name, not a localized one.
4. Source status
Active or inactive, before you change anything.
5. Folder Structure Retrieval
Its current settings, if you use the feature.
Upgrade every node that can run GFI Archiver AI or the polling service before you activate the Graph source.
Glossary
| Term | What it means here |
|---|---|
| EWS | Exchange Web Services. The retiring Exchange interface GFI Archiver AI used to read Microsoft 365 mail. |
| Microsoft Graph | Its modern, supported replacement. |
| Microsoft Entra ID | Microsoft’s identity portal, formerly Azure AD. Where you register the application. |
| Tenant ID / Client ID | From the application: the Directory (tenant) ID and the Application (client) ID. |
| Client secret | The application’s password. Shown once, so copy it to a secure store immediately. |
| Journal mailbox | The Microsoft 365 mailbox that receives a copy of all mail for GFI Archiver AI to store. |
PROCEDURE
The five steps
Follow them in order. Nothing is saved until GFI Archiver AI has tested the connection successfully, so a failed test never leaves you half-migrated.
Upgrade GFI Archiver AI
- Schedule a maintenance window and verify your current backups.
- Restart the server if Windows reports a pending restart.
- Run the new installer as Administrator over the existing installation. Do not uninstall the previous version.
- Wait for database updates and service restarts to finish. At the end of the installation the Bulk Schema Upgrader asks to upgrade each archive store.
- Verify under Configuration › Mail Servers › Add that Microsoft 365 / Microsoft Graph appears in the Connect using dropdown.
The journal mail server may show as deactivated until the schema upgrade completes. See Additional details for the Microsoft sign-in variant of the Bulk Schema Upgrader and what to do if the upgrade was skipped or failed.
Register a Microsoft Graph application
The simplest supported option is the application registration script shipped with GFI Archiver AI. One script is enough: New-GfiArchiverGraphApp.ps1 for a new application, or Update-GfiArchiverAzureAdAppForGraph.ps1 for an existing one.
New application
- Go to Configuration › Mail Servers › Add.
- Select Microsoft 365 / Microsoft Graph.
- Click Download app registration script to get
New-GfiArchiverGraphApp.ps1. - Run it in Windows PowerShell as a user with the required permissions.
.\New-GfiArchiverGraphApp.ps1 -TenantId "<tenant-id>"You can run the script from any Windows computer with internet access; it does not need to run on the GFI Archiver AI server. It installs the required Microsoft Graph PowerShell modules if they are missing, then prompts for device code sign-in and admin consent. Run it once – each run creates a new client secret.
Existing application
If GFI Archiver AI already has an application configured under Configuration › Azure AD, reuse it.
- In Configuration › Mail Servers › Add, select Microsoft 365 / Microsoft Graph and tick Use existing Azure AD/OAuth configuration. The Tenant ID, Client ID and Client Secret fields are hidden.
- Enter the journal mailbox and folder, then click Next. GFI Archiver AI tests the connection and saves the source if the test succeeds.
- If the application does not have the Graph permission yet, the test fails with “Microsoft Graph application permissions are missing. Required permission: Mail.ReadWrite. Update the Azure AD application registration and grant admin consent.” and offers a Download permissions update script link. The same file is available at https://<GFI Archiver server>/Archiver/GraphScriptDownload.aspx?script=update.
- Run the script in Windows PowerShell as a Microsoft Entra administrator, from any Windows computer with internet access.
.\Update-GfiArchiverAzureAdAppForGraph.ps1 -AppId "<application-client-id>" -TenantId "<tenant-id>"The script adds the Graph permissions, grants admin consent and keeps the existing EWS permissions. Add -CreateNewClientSecret only if you also need a new secret. Click Next again; the source is saved when the test succeeds.
Manual registration in the Entra portal
- 2a – Register: Entra ID › App registrations › New registration. Name it and click Register. On the Overview page, copy the Directory (tenant) ID and the Application (client) ID.
- 2b – Secret: Certificates & secrets › New client secret › Add. Copy the Value immediately.
- 2c – Permissions: API permissions › Add a permission › Microsoft Graph › Application permissions. Add the three permissions below, click Grant admin consent, and confirm each row shows Granted.
Restrict access to selected mailboxes (optional)
- Use Exchange Online RBAC for Applications to limit access to the target journal mailboxes.
- Remove organization-wide
Mail.ReadWriteseparately, and validate withTest-ServicePrincipalAuthorization.
Add the Graph source
- Go to Configuration › Mail Servers and select Add.
- Under Connect using, choose Microsoft 365 / Microsoft Graph.
- Select the credential type:
- Manual – enter Tenant ID, Client ID and Client Secret.
- Use existing Azure AD/OAuth configuration – uses the application saved under Configuration › Azure AD; the credential fields are hidden.
- Enter the exact journal mailbox SMTP address and the mailbox folder (Inbox) used by the EWS source.
- Click Next. GFI Archiver AI tests the connection and saves the source if the test succeeds. If the test fails, the message says what failed and nothing is saved.
For the migration, leave Public webhook base URL (optional) and Local listen URL empty. GFI Archiver AI then checks the mailbox every 30 seconds and no inbound connection is needed. Enable webhooks only if an external HTTPS endpoint and reverse proxy are already in place.
If an active EWS source reads the same journal mailbox and folder, GFI Archiver AI deactivates it and the last page says: “The EWS source ‘<name>’ for this mailbox was deactivated. Delete it once you have verified that Microsoft Graph archiving works.”
The new entry appears in Configuration › Mail Servers with the suffix -Graph, so it can be told apart from the EWS entry for the same mailbox.
Switch archiving from EWS to Graph
Open Configuration › Mail Servers and refresh the page. The Graph entry is Active and the EWS entry for the same mailbox is Inactive – GFI Archiver AI deactivated it when the Graph source was saved. Keep the EWS entry until your observation period is over; do not delete it yet.
If the EWS entry is still Active, for example because both were active before the upgrade, the Dashboard Event Viewer shows: “EWS source <name> and Microsoft Graph source <name> are both active for <mailbox>. Deactivate the EWS source.” Select the EWS entry and click Deactivate.
If several journal mailboxes or folders are configured, add the Graph counterpart for each. Each save deactivates its own EWS counterpart.
What to expect after the switch
- The deactivated EWS source no longer collects mail. Nothing already archived is removed.
- An EWS source added or edited while a Graph source for the same mailbox and folder is active is saved Inactive. This is intended: the Graph source wins on any save. The wizard’s last page reuses the migration wording and names the entry you just saved, so read it as “saved inactive” – the entry does not have to be deleted. To archive through EWS instead, deactivate the Graph source and then activate this entry.
- Messages that arrived in the journal mailbox while EWS was unavailable are archived as soon as the Graph source is active.
- After archiving a message through Microsoft Graph, GFI Archiver AI moves it to the journal mailbox’s Deleted Items folder. A message found there was archived – search the archive for it.
- Dashboard › Journaling Mailboxes keeps listing the deactivated EWS source with its last status, for example “Failed to connect”, until you delete the source.
Verify the result
- Send a test message that triggers the Exchange Online journal rule.
- Verify delivery in the target journal mailbox.
- Confirm GFI Archiver AI ingests the item with correct timestamps, senders and attachments. After archiving, the message is moved to the journal mailbox’s Deleted Items folder.
- Verify that no duplicates are created and that the old EWS source is Inactive.
Folder Structure Retrieval validation
Open Configuration › Folder Structure Retrieval and click Change Settings – or Enable Folder Structure Retrieval if the feature is disabled. Select Microsoft 365 / Microsoft Graph, tick Use existing Azure AD/OAuth configuration or enter the application credentials, and click Next. GFI Archiver AI tests the connection and saves the settings if the test succeeds. To test the saved settings later, use Test Connection on the Folder Structure Retrieval page.
Until you switch it, Folder Structure Retrieval keeps retrieving folders through EWS while the Graph mail server archives. Switch it before Microsoft disables EWS for your tenant.
PERMISSIONS
Required Microsoft Graph application permissions
Both scripts grant exactly these three. Use Application permissions, never Delegated, and grant admin consent after adding them.
| Permission | Purpose | Needed for archiving |
|---|---|---|
Mail.ReadWrite | Retrieve and process journal messages. | Required |
User.Read.All | Find users and mailboxes for Folder Structure Retrieval. Granted by default by the registration script. | Folder structure |
Application.Read.All | Lets the Dashboard warn before the client secret expires. Granted by both scripts. | Not required |
Folder Structure Retrieval also accepts alternatives you may already have: Directory.Read.All in place of User.Read.All, and Mail.Read in place of Mail.ReadWrite. If the application already has an alternative granted, Folder Structure Retrieval works and you do not need to add the permission named in the table.
Save the generated client secret immediately in a secure password store. Never share it by email or in a support ticket.
ROLLBACK
If Graph ingestion fails
Rollback is two steps, and the order matters. Nothing is activated automatically.
STEP 1
Deactivate the Graph source
Select the Graph source in Configuration › Mail Servers and click Deactivate.
STEP 2
Activate the EWS source
Select the EWS source and click Activate. Confirm archiving resumes over EWS while you investigate the Graph logs, and keep the Graph configuration intact during troubleshooting.
“‘<EWS source>’ cannot be activated because the Microsoft Graph source ‘<Graph source>’ for the same mailbox and folder is active. Deactivate ‘<Graph source>’ first.”
It works only while EWS still works in your tenant. After Microsoft starts disabling EWS on October 1, 2026 it requires Microsoft’s temporary opt-out, which ends on April 1, 2027. Tenant-side EWS changes can take hours to take effect. See Microsoft’s EwsAllowedAppIds announcement for the opt-out mechanism.
SCOPE
Known limitations
Plan around these before the maintenance window rather than during it.
Public folders
Public folders cannot be archived through Microsoft Graph.
Import/Export Tool
It can import mailboxes through Graph but cannot mark messages as exported, so repeating an export can export the same messages again.
Optional webhook
It needs a public HTTPS endpoint with a certificate from a public certification authority. Without it, GFI Archiver AI checks the mailbox every 30 seconds.
No event or email alerts
Graph problems are reported in the Dashboard client-secret warning, the health file and the Graph log only.
Interactive sign-in required
Registering the application and granting admin consent need an interactive Microsoft Entra administrator sign-in, which is why a PowerShell script is used.
No de-duplication
Messages archived while an EWS and a Graph source were both active for the same mailbox are not de-duplicated. GFI Archiver AI warns on the Dashboard; it never deletes the EWS entry for you.
TROUBLESHOOTING
Symptoms and what to check
Search by symptom, error text or file name. Seventeen documented cases.
Ensure all node servers are upgraded to the required release build, 15.14 or later.
Mail server wizard: “Microsoft Graph application permissions are missing. Required permission: Mail.ReadWrite. Update the Azure AD application registration and grant admin consent.”
Folder Structure Retrieval: “Microsoft Graph application permissions are missing. Required permissions: Mail.ReadWrite, User.Read.All. Update the Azure AD application registration and grant admin consent. The setup scripts also grant Application.Read.All for dashboard client secret expiry warnings; this permission is not required for mail access.”
Confirm that Application permissions (not Delegated) were assigned and that admin consent was granted. Both messages include a Download permissions update script link; run Update-GfiArchiverAzureAdAppForGraph.ps1 as described in step 2.
Verify the Tenant ID, Client ID and Client Secret, including validity and expiry.
Validate the SMTP address and use explicit folder naming – Inbox rather than a localized name.
Check the source’s active status, the journal rules and the execution timestamps in snapshot.json. Check the Graph log at …\GFI\Archiver\Core\DebugLogs\MArc.UMPolling.GraphPolling.log. Messages already in the journal mailbox’s Deleted Items were archived.
An EWS source and a Graph source were both active for the same mailbox, which is only possible for a configuration made before the upgrade.
Dashboard Event Viewer: “EWS source <name> and Microsoft Graph source <name> are both active for <mailbox>. Deactivate the EWS source.”
Deactivate the EWS source. Messages archived while both were active are not de-duplicated.
Ensure User.Read.All or Directory.Read.All application permissions are consented.
Clear the optional webhook fields to revert to polling every 30 seconds. If only one of the two fields is filled in, the wizard shows: “Enter a local listen URL when a public webhook URL is set.”
Re-run Update-GfiArchiverAzureAdAppForGraph.ps1 with -CreateNewClientSecret and update the GFI Archiver AI settings.
The log shows error 1921, “MARCore could not be stopped”. A restart was pending before the installer started. Restart the server and run the installer again.
No application is saved under Configuration › Azure AD. Configure it there first, or untick the box and enter the Tenant ID, Client ID and client secret manually.
Application.Read.All is missing, or the secret is wrong or expired, or Microsoft Graph is unreachable. Read snapshot.json and the Graph log to tell which.
See Upgrading to 15.14 below, and KB 105532.
The Graph source moves each message to Deleted Items after archiving it. Search the archive for the message.
Only one journal source per mailbox folder can be active. To switch back to EWS, deactivate the Graph source first, then activate the EWS source. See Rollback.
The last page says it “was deactivated. Delete it…”. A Graph source for the same mailbox and folder is active, so the EWS entry was saved inactive. The last page reuses the migration wording: the entry it names is the one just saved, and it does not have to be deleted. To archive through EWS instead, deactivate the Graph source, then activate the EWS entry.
GFI Archiver AI writes no Windows event and sends no email when the Graph source stops working. See Health and logs for exactly what you will see and where to look.
MONITORING
Health state and logs
Graph state and snapshot health logs are stored locally on each node. The health file contains no secret.
| What | Where |
|---|---|
| State directory | %ProgramData%\GFI\Archiver\GraphPolling\state |
| Health summary | %ProgramData%\GFI\Archiver\GraphPolling\state\health\snapshot.json |
| Graph log | …\GFI\Archiver\Core\DebugLogs\MArc.UMPolling.GraphPolling.log |
| EWS journal source logs | EWSProvider.log and DSScheduler.log in …\Core\DebugLogs |
| Folder Structure Retrieval over EWS | UMPoll.EWSPoll.log (process MArc.UMPolling.EWSPolling.exe) |
Run the GFI MA Debug Logs Tool. It collects the health file as GraphPollingHealth.zip together with the Graph log and the Bulk Schema Upgrader log.
The Graph poller is MArc.UMPolling.GraphPolling.exe, started by the GFI Archiver Core service. It polls every 30 seconds by default.
Both scripts can also be downloaded without going through a wizard: https://<GFI Archiver server>/Archiver/GraphScriptDownload.aspx?script=update for the permissions update script, and …?script=new for the application registration script.
REFERENCE
Additional details
Three things worth reading before the maintenance window, even if you do not hit them.
For a GFI Archiver AI EWS source, once EWS is disabled for your tenant or for the journal mailbox:
- new journal messages are no longer archived;
- the Dashboard Event Viewer shows no error and no notification email is sent; the Journaling Mailboxes panel may show the source as “Failed to connect”;
- Folder Structure Retrieval › Test Connection may still succeed;
- editing the EWS mail server and testing the connection fails with HTTP 403 Forbidden, and …\Core\DebugLogs\EWSProvider.log records “The request failed with HTTP status 403: Forbidden”;
- existing connections can keep working for some hours after the tenant setting changes.
Messages keep arriving in the journal mailbox during this time and are archived when the Graph source starts.
15.14 upgrades the archive-store database schema. At the end of the installation the Bulk Schema Upgrader asks to upgrade each store. A store is not used for archiving until its schema is upgraded, and the journal mail server may show as deactivated until then.
Installations that use Microsoft sign-in (Configuration › Azure AD)
The tool asks for the credentials of a GFI Archiver AI administrator. Enter the administrator’s Microsoft account (user principal name) as the user name, and a Microsoft Graph access token for that account as the password: open Microsoft Graph Explorer, sign in with that account and copy the value on the Access token tab. It is valid for about one hour. Select the stores and click Upgrade. If the tool reports that the credentials were not accepted for a store, enter that store’s SQL Server credentials at the second prompt. A Windows account cannot be used here, and the “grant the Administrator role” step of KB 105532 does not apply to Microsoft sign-in installations.
If the schema upgrade was skipped or failed
Run …\GFI\Archiver\BulkSchemaUpgrader\BulkSchemaUpgrader.exe, or open Configuration › Archive Stores, select the store flagged for upgrade, click Edit, re-enter the database credentials and complete the wizard. Then re-activate any deactivated mail server. Log: …\GFI\Archiver\BulkSchemaUpgrader\DebugLogs\GFIMailArchiverBulkSchemaUpgrader.log.
.NET Framework 4.8
Windows Server 2022 and later include it; on earlier versions install it first. A silent (/qn) upgrade is also blocked when it is missing.
GFI Archiver AI does not write a Windows event or send an email when the Graph source stops working. What you will see:
- Dashboard › Event Viewer: “Unable to check client secret expiry for <source>…”, shown when the secret is wrong or expired and also when Microsoft Graph cannot be reached. It does not name the cause.
- Configuration › Mail Servers: the source still shows Active.
- snapshot.json:
status,lastGraphHttpStatusSummaryandlastJournalLocationErrorByDataSourceshow the last error;lastJournalRunUtcByDataSourcestops advancing. Other fields:lastSuccessfulDeltaCheckpointByWorker,webhookListenerStatus. - Graph log: the error with its HTTP status.
Ready to migrate?
Download GFI Archiver AI 15.14 from the Upgrade Center, then work through the five steps above. Support and your GFI partner can help you plan the maintenance window.