# Migrating GFI Archiver from EWS to Microsoft Graph

> Step-by-step guide to moving GFI Archiver AI Exchange Online journal archiving from EWS to Microsoft Graph, with no historical archive data migration.

Source: https://gfi.ai/migrating-ews-microsoft-graph/
Last updated: 2026-10-21

---

- Migration guide · Archiver AI 15.14+

## 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

[Read the KB article](https://support.archiver.gfi.com/article/135348-gfi-archiver-ai-migrating-from-ews-to-microsoft-graph)

###### EWS RETIREMENT TIMELINE

NOW

Upgrade to **15.14**, register the Graph application and switch your journal sources.

OCT 1, 2026

Microsoft begins **blocking EWS** for Exchange Online tenants. Rollback then needs Microsoft’s temporary opt-out.

APR 1, 2027

EWS is **removed permanently**. The opt-out ends.

ON-PREM

Exchange Server on-premises is **not affected** by this retirement.

###### ON THIS PAGE

- Overview
- Before you start
- The five steps
- Graph permissions
- Rollback
- Known limitations
- Troubleshooting
- Health & logs
- Additional details

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.

Stays exactly as it is

- Every message already in your archive
- Exchange Online journaling rules
- The journal mailbox itself
- Archive stores, retention and search

Changes

- New journal messages are retrieved over Microsoft Graph
- A new mail server source is added with the `-Graph` suffix
- The matching EWS source is deactivated automatically
- Archived messages move to the journal mailbox’s Deleted Items

One active source per mailbox folder

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.

Distributed installations

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.

1

#### Upgrade GFI Archiver AI

1. Schedule a maintenance window and verify your 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 finish. At the end of the installation the **Bulk Schema Upgrader** asks to upgrade each archive store.
5. Verify under **Configuration › Mail Servers › Add** that **Microsoft 365 / Microsoft Graph** appears in the **Connect using** dropdown.

A store is not used for archiving until its schema is upgraded

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.

2

#### 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

1. Go to **Configuration › Mail Servers › Add**.
2. Select **Microsoft 365 / Microsoft Graph**.
3. Click **Download app registration script** to get `New-GfiArchiverGraphApp.ps1`.
4. 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.

1. 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.
2. Enter the **journal mailbox** and **folder**, then click **Next**. GFI Archiver AI tests the connection and saves the source if the test succeeds.
3. 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.
4. 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.ReadWrite` separately, and validate with `Test-ServicePrincipalAuthorization`.

3

#### Add the Graph source

1. Go to **Configuration › Mail Servers** and select **Add**.
2. Under **Connect using**, choose **Microsoft 365 / Microsoft Graph**.
3. 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.
4. Enter the **exact journal mailbox SMTP address** and the **mailbox folder** (Inbox) used by the EWS source.
5. 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.

Webhooks: leave them empty

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.

4

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

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

You can switch it later, but not much later

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.

Handle the client secret properly

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.

Activate is refused in the wrong order

*“‘<EWS source>’ cannot be activated because the Microsoft Graph source ‘<Graph source>’ for the same mailbox and folder is active. Deactivate ‘<Graph source>’ first.”*

Rollback has an expiry date

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](https://techcommunity.microsoft.com/blog/exchange/introducing-ewsallowedappids-preparing-for-the-final-phase-of-ews-retirement/4529471) 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.

### Microsoft Graph is missing from the options

Ensure all node servers are upgraded to the required release build, 15.14 or later.

### Application permissions are missing

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.

### 400, 401 or 403 authorization errors

Verify the Tenant ID, Client ID and Client Secret, including validity and expiry.

### Journal mailbox or folder not found

Validate the SMTP address and use explicit folder naming – `Inbox` rather than a localized name.

### New messages are not appearing in the archive

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.

### Duplicate messages occurring

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.

### Folder Structure Retrieval fails

Ensure `User.Read.All` or `Directory.Read.All` application permissions are consented.

### Webhook registration errors

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

### Lost or expired client secret

Re-run `Update-GfiArchiverAzureAdAppForGraph.ps1` with `-CreateNewClientSecret` and update the GFI Archiver AI settings.

### The upgrade rolls back with Windows Installer error 1603

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.

### "Existing Azure AD/OAuth configuration is not available or is missing tenant ID, client ID, or client secret"

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.

### "Unable to check client secret expiry for <source>…" on the Dashboard

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

### Bulk Schema Upgrader shows an empty store list or "Error retrieving databases"

See Upgrading to 15.14 below, and KB 105532.

### A journal message is not visible in the archive, but is in the journal mailbox's Deleted Items

The Graph source moves each message to Deleted Items after archiving it. Search the archive for the message.

### "'<EWS source>' cannot be activated because the Microsoft Graph source '<Graph source>' for the same mailbox and folder is active"

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.

### A newly added EWS mail server is Inactive right after the wizard finishes

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.

### Archiving stopped after a successful migration

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) |

Contacting Support

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.

### What happens when Microsoft disables EWS

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.

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

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

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`, `lastGraphHttpStatusSummary` and `lastJournalLocationErrorByDataSource` show the last error; `lastJournalRunUtcByDataSource` stops 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.

[Upgrade Center](https://upgrade.gfi.com/?product=gfi-archiver)

[15.14 release notes](https://gfi.ai/resource/archiver-product-releases/)

[Contact Support](https://support.archiver.gfi.com/login)

### Need help with the migration?

Read the full knowledge base article, or contact our team if Graph ingestion does not behave as described in this guide.

[Read the KB article →](https://support.archiver.gfi.com/article/135348-gfi-archiver-ai-migrating-from-ews-to-microsoft-graph)

[Contact support →](https://customercare.gfi.com/)
