Migrating from Legacy

This guide is for system administrators upgrading from the legacy Nextcloud Exchange Connector to the new architecture.

The new architecture represents a complete paradigm shift. The synchronization engine is no longer restricted by Nextcloud's internal cron jobs. It is now a powerful, decoupled microservice.

Because of this architectural upgrade, the way you configure the application has completely changed. You will no longer edit docker-compose.yml or appsettings.json. All settings have been unified into a single .env file. Exchange and Nextcloud connections are no longer a flat Service__* block: you declare sync clients (EventSyncClients) and a pair that points at them. A separate admins.json file is optional and only needed if you want a pool of Exchange admin accounts.

Prerequisites

Before starting the migration process:

1. Back up your database: Always create a full snapshot or dump of your existing database before performing major upgrades.

2. Keep your old config files handy: Do not delete your old docker-compose.yml or appsettings.json yet. You will need to copy the values from them during the mapping phase.

3. Read the following article, how it impacts your users LINK.

Upgrade steps

Complete these steps in this order:

1. Stop the Nextcloud Exchange Connector service. Make sure it is not running before you continue.

2. Update the Sendent Sync app in Nextcloud to version 2.1.0.

3. Pull the new Exchange Connector image using the 2.0.0 tag (or latest).

4. Apply the configuration changes described this migration article.
   Check that all required setting changes are in place.

5. Start the Nextcloud Exchange Connector service.

6. Inform your users that they will be asked to give consent again, and that they should accept the calendar recreation notice.

Step 1. Disable Legacy Background Tasks

If the legacy background synchronization tasks and the new worker run simultaneously, they will overwrite each other, causing massive duplication of calendar events and contacts.

You must stop the old synchronization engine from executing. Depending on how your legacy application was configured, you need to remove or disable the specific cron jobs (scheduled tasks) on your Nextcloud server that trigger the old synchronization scripts.

Step 2. Preserve Your Database

The new application is fully compatible with your existing database. Because the user tokens and synchronization watermarks are preserved in the old tables, migrating your database connection ensures a seamless transition:

• No massive "Initial Sync": The system will simply pick up exactly where it left off.

• No user re-consent required: Your Nextcloud users do not need to click the "Grant Access" button again. Their existing consent tokens will continue to work flawlessly.

Step 3. Prepare the Deployment Files

Navigate to the Docker Compose Deployment Files article and copy the required .yml configurations. Save them as standard text files inside your new directory, ensuring the filenames match exactly.

The provided configuration will automatically pull the latest official container image from the public repository: rg.nl-ams.scw.cloud/sendent-public/sendent-sync:latest

Step 4. The Configuration Mapping

You must manually translate your old configuration values into the new architecture using the .env file. An admins.json file is optional (Step 4.3)

environment:
  - Service__NextcloudBaseUrl=https://nc01.sendent.dev
  - Service__NextcloudServiceUsername=admin
  - Service__MicrosoftTenantId=df6e89a5-...
  - Service__ExchangeType=1
  - ConnectionStrings__DatabaseConnectionString=Host=sendent.synchronisation.db;Port=5432;...

DatabaseConfiguration__ConnectionString=Host=sendent.synchronisation.db;Port=5432;...
EventSyncClients__0__Identifier=ews
EventSyncClients__0__Provider=Ews
EventSyncClients__0__Settings__ExchangeType=1
EventSyncClients__0__Settings__TenantId=df6e89a5-...
EventSyncClients__0__Settings__AppId=your-app-id
EventSyncClients__0__Settings__ClientSecret=your-client-secret
EventSyncClients__1__Identifier=dav
EventSyncClients__1__Provider=Dav
EventSyncClients__1__Settings__BaseUrl=https://nc01.sendent.dev
EventSyncClients__1__Settings__ServiceUsername=admin
EventSyncClients__1__Settings__ServicePassword=your-password
EventSyncClients__1__Settings__SharedSecret=your-shared-secret
EventSync__Pairs__0__SourceClientId=ews
EventSync__Pairs__0__TargetClientId=dav
EventSync__CalendarPriorityOrder__0=ews
EventSync__CalendarPriorityOrder__1=dav

Step 4.1: General Settings (Move to .env)

Open your new .env file and map your old appsettings.json or docker-compose.yml variables exactly as follows:

Indexes __0__ / __1__ match the examples: 0 = Exchange (EWS or Graph), 1 = Nextcloud (DAV). ExchangeType, OnPremUrl, and OnPremDomain apply to EWS only. Graph uses TenantId / AppId / ClientSecret and has no on-prem URL.

Step 4.2: Sync clients (required)

The mapping in Step 4.1 is not enough on its own. You must declare the clients and a pair. Identifier values must match EventSync__Pairs.

Provider is Ews, Dav, or Graph. Settings depend on that provider.

Copy one Exchange-side block (A, B, or C) plus the DAV client. Do not mix A/B/C in the same .env.

A. Microsoft 365 via EWS

Use this if the old config had Service__ExchangeType=1 and you are staying on EWS.

EventSyncClients__0__Identifier=ews
EventSyncClients__0__Provider=Ews
EventSyncClients__0__Settings__ExchangeType=1
EventSyncClients__0__Settings__TenantId=yyy
EventSyncClients__0__Settings__AppId=zzz
EventSyncClients__0__Settings__ClientSecret=xxx
 
EventSyncClients__1__Identifier=dav
EventSyncClients__1__Provider=Dav
EventSyncClients__1__Settings__BaseUrl=https://cloud.example.com/
EventSyncClients__1__Settings__ServiceUsername=sync-admin
EventSyncClients__1__Settings__ServicePassword=xxx
EventSyncClients__1__Settings__SharedSecret=xxx
 
EventSync__Pairs__0__SourceClientId=ews
EventSync__Pairs__0__TargetClientId=dav
EventSync__CalendarPriorityOrder__0=ews
EventSync__CalendarPriorityOrder__1=dav

Do not put ExchangeAdminRaw under EventSyncClients__*__Settings. A single app registration is enough on the client. An admin JSON array, if you still use one, stays at Service__ExchangeConfiguration__ExchangeAdminRaw (see Step 4.3).

B. Microsoft 365 via Graph API

Graph is a different Provider, not another ExchangeType. Use this only after you registered a Graph app. Tenant can stay the same; AppId and ClientSecret are the Graph app, not the old EWS app.

DAV keys are the same as in A.

EventSyncClients__0__Identifier=graph
EventSyncClients__0__Provider=Graph
EventSyncClients__0__Settings__TenantId=yyy
EventSyncClients__0__Settings__AppId=zzz
EventSyncClients__0__Settings__ClientSecret=xxx
 
EventSyncClients__1__Identifier=dav
EventSyncClients__1__Provider=Dav
EventSyncClients__1__Settings__BaseUrl=https://cloud.example.com/
EventSyncClients__1__Settings__ServiceUsername=sync-admin
EventSyncClients__1__Settings__ServicePassword=xxx
EventSyncClients__1__Settings__SharedSecret=xxx
 
EventSync__Pairs__0__SourceClientId=graph
EventSync__Pairs__0__TargetClientId=dav
EventSync__CalendarPriorityOrder__0=graph
EventSync__CalendarPriorityOrder__1=dav

Graph has no ExchangeType, OnPremUrl, or OnPremDomain.

C. On-premise Exchange (Kerberos)

Use this if the old config had Service__ExchangeType=2. Graph does not apply on-premise.

EventSyncClients__0__Identifier=ews
EventSyncClients__0__Provider=Ews
EventSyncClients__0__Settings__ExchangeType=2
EventSyncClients__0__Settings__OnPremUrl=https://exchange.example.com/EWS/Exchange.asmx
EventSyncClients__0__Settings__OnPremDomain=example.com
EventSyncClients__0__Settings__UserName=sync-admin
EventSyncClients__0__Settings__Password=xxx
 
EventSyncClients__1__Identifier=dav
EventSyncClients__1__Provider=Dav
EventSyncClients__1__Settings__BaseUrl=https://cloud.example.com/
EventSyncClients__1__Settings__ServiceUsername=sync-admin
EventSyncClients__1__Settings__ServicePassword=xxx
EventSyncClients__1__Settings__SharedSecret=xxx
 
EventSync__Pairs__0__SourceClientId=ews
EventSync__Pairs__0__TargetClientId=dav
EventSync__CalendarPriorityOrder__0=ews
EventSync__CalendarPriorityOrder__1=dav

ExchangeType=3 (Basic Auth) uses the same client keys as Kerberos. ExchangeType=4 (ADFS) uses OnPremUrl, OnPremAdfsAuthorityUrl, ClientId, and ClientSecret instead of UserName / Password.

Step 4.3: Administrator Credentials (optional - admins.json)

If you already set AppId / ClientSecret (cloud) or UserName / Password (on-premise) on the Exchange client in Step 4.2, the connector can run with that single account. Create admins.json only when you need several Exchange admin identities to spread load and avoid throttling.

1. Inside your deployment folder, create a directory named exchangeAdmins.

2. Create a file named admins.json inside it.

3. If you need a pool, put extra admin identities in this JSON array. The first account can stay on the client in Step 4.2; extra accounts go here.

[
  {
    "AppId": "your_old_MicrosoftAppId_value",
    "ClientSecret": "your_old_MicrosoftClientSecret_value"
  }
]

[
  {
    "Username": "your_old_ExchangeOnPremUsername_value",
    "Password": "your_old_ExchangeOnPremPassword_value"
  }
]

admins.json and Service__ExchangeConfiguration__ExchangeAdminRaw feed the admin pool. They do not replace client Settings such as OnPremUrl, OnPremDomain, or TenantId. Those stay on EventSyncClients.

Do not put ExchangeAdminRaw under EventSyncClients__*__Settings. If you use an inline JSON array, the key is Service__ExchangeConfiguration__ExchangeAdminRaw.

For a Graph pool, each object also needs "Provider": "Graph". Without that field the pool is treated as EWS.

Refer to Managing Service Accounts (admins.json) article to know more about managing service accounts.

Step 4.4: New Configuration Variables

The new architecture introduces several settings that were not present in the legacy appsettings.json or docker-compose.yml configurations. These new parameters provide granular control over scaling, data privacy, and logging.

You can configure these in your new .env file.

Step 5. Start the New Worker

Once your .env file is fully mapped (and admins.json, if you created one) within your extracted deployment folder (from Step 3), and your legacy background processes are disabled, you can safely start the new worker.

The Sendent deployment is modular. You must build your startup command by appending -f flags depending on which database and monitoring tools you want Docker to host for you.

Build your command by starting with the base file, appending your optional components, and ending with up:

1. The Base Command (Required): docker compose -f docker-compose.yml

2. Append a Database Container (Skip if you're using an external database)

• For PostgreSQL: -f docker-compose.postgres.yml

• For MariaDB: -f docker-compose.mariadb.yml

• For SQL Server: -f docker-compose.sqlserver.yml

3. Append Monitoring (Optional):

• For Loki & Grafana: -f docker-compose.grafana.yml

Examples of complete commands:

Running with a local PostgreSQL container and Grafana:

docker compose -f docker-compose.yml -f docker-compose.postgres.yml -f docker-compose.grafana.yml up

Running with an external database (no local DB container) and no Grafana:

docker compose -f docker-compose.yml up

The application will automatically connect to your existing database, read the old tokens, and seamlessly resume synchronizing user data.

Step 6. Configure Logging

The logging architecture has been completely redesigned. You will no longer define complex Serilog objects in appsettings.json. Instead, you control logging through bitwise values in the .env file.

For comprehensive instructions on configuring alternative logging methods (such as Grafana or File System), please refer to Logging & Monitoring.

Clean-up

After verifying that the new worker is running and synchronization is occurring smoothly via the logs, safely archive or delete your old docker-compose.yml and appsettings.json files to prevent future configuration confusion.