Moving documents to SharePoint Online without moving the users

Retiring a CRM by keeping its data is the structured half of leaving an old platform. The unstructured half is the documents: the signed forms, statements and correspondence a regulated business has to be able to produce on request.

In a recent engagement those documents live in an on-premises SharePoint farm, surfaced to staff through a document panel inside Dynamics 365. Staff open a client or a case, see which documents are required and which exist, and work with them without ever knowing SharePoint is involved. The farm has to go. The panel, and the way people work with it, has to stay exactly as it is.

The seam was already in the right place

We started with an architecture review of the existing service, and the most useful finding was a reassuring one. Every operation against SharePoint already went through a single data-access interface, and a second implementation of that interface, written for SharePoint Online, existed and was built on every branch. Which one runs is decided by one registration in each host.

That means the move is not a rewrite. Nothing the users touch has to change. The migration becomes a credential, a release pipeline, a search configuration, a set of source records and a data move.

It also made the rest of the review honest. Once you know the code change is small, it is obvious that the risk is somewhere else.

Where the risk actually sits

Identity. SharePoint Online does not accept the kind of app-only token the old integration used. It needs certificate-based authentication through Entra ID. The code for that path was written and tested well before the certificate itself was issued, which made a piece of administration the single blocking dependency for the whole migration until it cleared in August.

Search. The panel relies on search to find documents. In SharePoint Online, the managed properties that search depends on have to exist in the tenant's schema, and the target libraries have to carry columns with exactly the internal names the service writes. Get either wrong and search quietly returns nothing.

Throttling. SharePoint Online protects itself far more aggressively than an on-premises farm. A search that fans out into many parallel requests works on premises and gets throttled in the cloud, so concurrency needs a cap before any bulk validation begins.

Release plumbing. The build already produced the online version of the service, but at first nothing deployed it. Adding it touched both the pipeline definition and the release definition, which is exactly the kind of small change that goes wrong when it is done in a hurry.

Configuration as data

One design decision makes the cut-over safer than it would otherwise be. The SharePoint endpoints the service uses live in a database table, maintained through the system's own administration site. An environment can be pointed at the new libraries, and pointed back again if something is wrong, without a deployment.

That turns a cut-over from a single irreversible event into a controlled step with a way back, which is what anybody responsible for regulated documents should expect.

Where to start

Before migrating anything wired into daily work, find out whether there is one seam between the application and its storage, and protect it. Where there is none, creating one is usually the cheapest first project.

Our approach to this kind of work is described under legacy modernisation and cloud migration and modernisation.