GFI Archiver AI: Migrating from EWS to Microsoft Graph

Purpose: Move Exchange Online journal archiving to Microsoft Graph without moving historical archive data. Applies to GFI Archiver 15.14 and later. Microsoft retires Exchange Web Services (EWS) in Exchange Online in phases from 1 October 2026 and removes it on 1 April 2027; Exchange Server on-premises is not affected. Complete this migration before October 2026. See What happens when Microsoft disables EWS at the end of this article.

This guide applies to any GFI Archiver 15.14 release where the mail server wizard includes Microsoft 365 / Microsoft Graph. During the migration:

• Existing GFI Archiver messages remain in the current archive.

• Exchange Online journaling rules and the journal mailbox remain in place.

• Only the method used to retrieve new journal messages changes.

• An existing EWS source is not converted by editing it; add a new Graph source instead.

📌 Caution: GFI Archiver keeps one active journal source per mailbox folder. When you save a Microsoft Graph source, the EWS source for the same journal mailbox and folder is deactivated automatically and the wizard’s last page names it. Keep the EWS entry until you have verified that Graph archiving works, then delete it. Each source removes a message from the journal mailbox after archiving it, so a configuration in which both are active (made before the upgrade) can archive a message twice; the Dashboard warns about it.

Before You Start

---

Prerequisites

• GFI Archiver installer for a release with Microsoft Graph support (15.14 or later).

• GFI Archiver 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 configuration and databases.

• Restart the server first if Windows reports a pending restart; otherwise the upgrade can fail to stop the GFI Archiver services and roll back.

• Microsoft .NET Framework 4.8 on the GFI Archiver server. 15.14 is the first release that requires it. If it is missing, the installer lists it as a missing requirement and stops. Install .NET Framework 4.8, restart if asked, and run the installer again.

• Outbound HTTPS access from the GFI Archiver server to Microsoft Graph and Microsoft Entra ID.

• A supported operating system; see System Requirements for Archiver.

• Windows PowerShell 5.1 or later to run the application registration script.

Record Current EWS Source Configuration

Before upgrading, record the following details:

1. Source name and the server/node where it runs.

2. Journal mailbox address.

3. Journal mailbox folder (usually Inbox).

4. Source status.

5. Folder Structure Retrieval settings (if utilized).

📝 Note for distributed installations: Upgrade every node that can run GFI Archiver or the polling service before activating the Graph source.

Glossary

• EWS — The retiring Exchange interface Archiver 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 app.

• Tenant ID / Client ID — From the app: the Directory (tenant) ID and Application (client) ID.

• Client Secret — The app's password; shown once, so copy it securely.

• Journal mailbox — The Microsoft 365 mailbox that receives a copy of all mail for Archiver to store.

1. Upgrade GFI Archiver

1. Schedule a maintenance window and verify current backups.

2. Restart the server if Windows reports a pending restart.

3. Run the new installer as Administrator over the existing installation (do not uninstall the previous version).

4. Wait for database updates and service restarts to complete. At the end of the installation the Bulk Schema Upgrader asks to upgrade each archive store; see Upgrading to 15.14: schema upgrade and Microsoft sign-in at the end of this article.

5. Verify by checking Configuration > Mail Servers > Add. Ensure Microsoft 365 / Microsoft Graph appears under the Connect using dropdown.

2. Register a Microsoft Graph Application

The simplest supported option is using the application registration script provided within GFI Archiver. One script is enough: New-GfiArchiverGraphApp.ps1 for a new application, or Update-GfiArchiverAzureAdAppForGraph.ps1 for an existing one.

New Application Setup

1. Navigate to Configuration > Mail Servers > Add.

2. Select Microsoft 365 / Microsoft Graph.

3. Click Download app registration script to download New-GfiArchiverGraphApp.ps1.

4. Run the script 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 server. Run the script once; each run creates a new client secret.

The script installs required Microsoft Graph PowerShell modules if missing. Follow the device code sign-in prompt and grant admin consent.

Manual Registration in the Entra Portal

• 2a — Register: Go to Entra ID > App registrations > New registration. Name it and click Register. On the Overview page, copy the Directory (tenant) ID and Application (client) ID.

• 2b — Secret: Navigate to Certificates & secrets > New client secret > Add. Copy the Value immediately.

• 2c — Permissions: Go to API permissions > Add a permission > Microsoft Graph > Application permissions. Add the permissions outlined below, click Grant admin consent, and confirm each row shows Granted.

Required Microsoft Graph Application Permissions

Both scripts grant exactly these three permissions. 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 the table names.

📝 Note: Use Application permissions, not Delegated permissions. Admin consent must be granted after permissions are added. Save the generated client secret immediately in a secure password store (do not share via email or support tickets).

Existing Application Setup

If GFI Archiver already has an application configured under Configuration > Azure AD, reuse it:

1. In Configuration > Mail Servers > Add, select Microsoft 365 / Microsoft Graph and tick Use existing Azure AD/OAuth configuration. The saved application is used; the Tenant ID, Client ID and Client Secret fields are hidden.

2. Enter the Journal mailbox and Folder and click Next. GFI Archiver tests the connection and, if the test succeeds, saves the source. An active EWS source for the same mailbox and folder is deactivated at this point and named on the last page (see section 4).

3. If the application does not yet have the Graph permission, 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). Download Update-GfiArchiverAzureAdAppForGraph.ps1 and run it in Windows PowerShell as a Microsoft Entra administrator. You can run it from any Windows computer with Internet access.

.\Update-GfiArchiverAzureAdAppForGraph.ps1 -AppId "<application-client-id>" -TenantId "<tenant-id>"

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

2. Click Next again. The source is saved when the test succeeds.

Restrict Access to Selected Mailboxes (Optional)

To scope permissions rather than granting organization-wide access:

• Use Exchange Online RBAC for Applications to limit access to target journal mailboxes.

• Remove organization-wide Mail.ReadWrite separately and validate using Test-ServicePrincipalAuthorization.

3. Add the Graph Source

1. Navigate to Configuration > Mail Servers and select Add.

2. Under Connect using, choose Microsoft 365 / Microsoft Graph.

3. Select 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 Tenant ID, Client ID and Client Secret fields are hidden.

4. Enter the exact Journal mailbox SMTP address and Mailbox folder (Inbox) used by the EWS source.

Webhook Configuration

For the migration leave Public webhook base URL (optional) and Local listen URL empty. GFI Archiver then checks the mailbox every 30 seconds; no inbound connection is needed. Enable webhooks only if an external HTTPS endpoint and reverse proxy are already established.

1. Click Next. GFI Archiver tests the connection and, if the test succeeds, saves the source. If the test fails, the message says what failed and nothing is saved.

2. If an active EWS source reads the same journal mailbox and folder, GFI Archiver 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.

4. Switch Archiving from EWS to Graph

After the Graph source is saved, 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 deactivated it when the Graph source was saved. Keep the EWS entry until the 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 have just saved: “The EWS source '<name>' for this mailbox was deactivated. Delete it once you have verified that Microsoft Graph archiving works.” 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 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.

5. Verify the Result

1. Send a test message that triggers the Exchange Online journal rule.

2. Verify delivery in the target journal mailbox.

3. Confirm GFI Archiver ingests the item with correct timestamps, senders, and attachments. After archiving, the message is moved to the journal mailbox's Deleted Items folder.

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

You can switch Folder Structure Retrieval in the same maintenance window or later. Until you switch it, it keeps retrieving folders through EWS while the Graph mail server archives. Switch it before Microsoft disables EWS for your tenant.

Folder Structure Retrieval Wizard configured with manual Graph credentials.

Folder Structure Retrieval Wizard using the existing Azure AD/OAuth configuration.

Checking Graph Health State

Graph state and snapshot health logs are stored locally on each node:

• 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

When contacting Support, run the GFI MA Debug Logs Tool; it collects the health file and the log. For the fields in snapshot.json and what to look at when archiving stops, see If Graph archiving stops: what you see and where to look at the end of this article.

Rollback Procedure

If Graph ingestion fails, rollback is two steps, in this order:

1. Select the Graph source and click Deactivate.

2. Select the EWS source and click Activate.

Activate is refused while the Graph source is still active: “'<EWS source>' cannot be activated because the Microsoft Graph source '<Graph source>' for the same mailbox and folder is active. Deactivate '<Graph source>' first.” Nothing is activated automatically. Confirm archiving resumes via EWS while investigating the Graph logs; keep the Graph configuration intact during troubleshooting.

📝 Note: Rollback works only while EWS still works in your tenant. After Microsoft starts disabling EWS (from 1 October 2026) it requires Microsoft's temporary opt-out, which ends on 1 April 2027. Tenant-side EWS changes can take hours to take effect.

Known Limitations

• Public folders cannot be archived through Microsoft Graph.

• The Import/Export Tool can import mailboxes through Microsoft Graph but cannot mark messages as exported; repeating an export can export the same messages again.

• The optional webhook needs a public HTTPS endpoint with a certificate from a public certification authority. Without it GFI Archiver checks the mailbox every 30 seconds.

• Graph problems are reported in the Dashboard client-secret warning, the health file and the Graph log; there is no Windows event or e-mail notification.

• Registering the application and granting admin consent need an interactive Microsoft Entra administrator sign-in, which is why a PowerShell script is used.

• Messages archived while an EWS source and a Graph source were both active for the same mailbox (a configuration made before the upgrade) are not de-duplicated. GFI Archiver warns on the Dashboard; it never deletes the EWS entry for you.

Troubleshooting & Common Issues

If Graph archiving stops after a successful migration, see also If Graph archiving stops: what you see and where to look at the end of this article.

Additional Details

> What happens when Microsoft disables EWS

For a GFI Archiver 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 e-mail 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.

> Upgrading to 15.14: schema upgrade and Microsoft sign-in

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

> If Graph archiving stops: what you see and where to look

GFI Archiver does not write a Windows event or send an e-mail 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.

• %ProgramData%\GFI\Archiver\GraphPolling\state\health\snapshot.json: status, lastGraphHttpStatusSummary and lastJournalLocationErrorByDataSource show the last error; lastJournalRunUtcByDataSource stops advancing. Other fields: lastSuccessfulDeltaCheckpointByWorker, webhookListenerStatus. The file contains no secret.

• …\GFI\Archiver\Core\DebugLogs\MArc.UMPolling.GraphPolling.log: the error with its HTTP status.

Other logs in …\GFI\Archiver\Core\DebugLogs: the EWS journal source writes EWSProvider.log and DSScheduler.log; Folder Structure Retrieval over EWS writes UMPoll.EWSPoll.log (process MArc.UMPolling.EWSPolling.exe).

The Graph poller is MArc.UMPolling.GraphPolling.exe, started by the GFI Archiver Core service; it polls every 30 seconds by default. The GFI MA Debug Logs Tool collects the health file as GraphPollingHealth.zip together with the Bulk Schema Upgrader log.

Both scripts can 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.