Originally published at migrationparity.com.
I recently took a quality-management workflow application — roughly 9,000 documents accumulated
over two decades in a single NSF — from Lotus Notes/Domino to .NET 8 with a SQL backend. The
export part that every migration tool advertises took days. The part that took months was
everything the brochures do not mention.
This is the list I wish I had at the start: the six places a Notes migration actually breaks,
and what to do about each.
1. There is no schema — there are 25 years of schemas
A Notes document is a bag of items. The form defines what new documents get; every old
document keeps whatever fields it was saved with, under whichever version of the form existed
that year. In practice our "one form" was a geological record: fields that appear only in
documents from 2003–2007, fields renamed twice, fields whose type quietly changed from text to
multi-value.
What works: inventory the documents, not the form. Scan every document's item names and
types, cluster by generation, and design the SQL schema against the union — with explicit
migration rules per generation. Any mapping built from the current form design alone will drop
data silently.
2. Rich text is a container format wearing a text costume
Notes rich-text fields hold formatted text — plus embedded images, file attachments, OLE
objects (that spreadsheet someone pasted in 2009), collapsible sections, tables, and doc links
pointing at other documents in other databases. A naive HTML export flattens this into soup;
a text export just deletes it.
What works: treat rich text as a document tree. Convert formatting to sane HTML, extract
attachments and images to real storage with references, and translate doc links into links in
the new system — which means migrating link targets first or maintaining a UNID-to-new-ID
map for the whole estate. Budget real time here: rich-text fidelity was our single largest
line item.
3. Reader fields: the security model that migrations silently drop
Reader and author fields make documents invisible to unauthorized users — enforced by the
database engine itself. Confidential HR cases, supplier complaints, audit findings: in Notes,
users literally cannot see documents they are not named in. Export the documents to SQL,
build a pretty new UI, forget this layer — and on day one every user can read everything.
This is the most dangerous failure mode in Notes migration, because nothing looks broken.
What works: extract the effective access model — ACLs, roles, groups (expanded via the
directory), reader/author items per document — and reproduce it as row-level security in the
new system. Then test it as identities: log in as a sampled set of real users on both systems
and diff what each can see.
4. Roles fan out into hundreds of decisions
The application had a handful of ACL roles — approver, coordinator, quality, admin. Innocent
looking. But roles are referenced in form formulas, view selection formulas, hide-when clauses,
agent logic and workflow-state transitions. Mapped onto the new system's authorization model,
our modest role list exploded into hundreds of individual mapping decisions — who may press
this button in this state, who sees this view, who gets this escalation. It became the go-live
blocker; not because any single decision was hard, but because each one needed a business owner
to say yes.
What works: surface this early. Machine-extract every role reference, generate the decision
matrix in week one, and put a named human owner on it. It is the longest-lead item in the whole
project precisely because it is not a technical task.
5. Views and agents are the application
Users do not experience "documents" — they experience views: selection formulas, categorized
columns, computed values, twisties. And the workflow does not run itself — scheduled agents
reassign, notify, escalate. Some agents encode the real process; some have been failing
silently for a decade and the business adapted around the failure (which means reviving them
faithfully would break the current process!).
What works: rebuild views as queries against the new schema, with the parity discipline of
diffing view contents between systems on frozen data. For agents: inventory, then observe —
which ones actually fired last year, what they changed — before deciding which to reproduce,
which to redesign, and which to let die officially.
6. Cutover is a coexistence problem, not an event
Nine thousand documents of living workflow cannot stop for a migration weekend. The old and new
systems overlap: new cases open in .NET while old cases finish their lifecycle in Notes, or
historical documents remain readable in Notes long after writes moved.
What works: plan the bridge deliberately. COM interop against the Notes client (or Domino's
HTTP interfaces) lets the new system read live Notes data during the transition — clunky but
effective; keep the bridge component registered and documented until the last dependency is
gone, then remove it on purpose rather than leaving it as a permanent mystery service. Retire
Domino to read-only, then to archive, only after a full business cycle proves nothing still
reaches for it.
The shape of the effort
For our ~9,000-document application, the honest cost breakdown was approximately:
| Workstream | Share of effort |
|---|---|
| Rich text, attachments, doc links | ~30% |
| Security model + role mapping decisions | ~25% |
| Schema archaeology & document migration | ~20% |
| Views, agents, workflow reproduction | ~15% |
| Coexistence bridge & cutover | ~10% |
Note what is not on the list: "exporting the documents". That part is a solved problem. The
project is everything around it — which is why per-document licensing of export tools tells
you almost nothing about what a Notes migration will cost.
This experience is packaged as our
Lotus Notes / Domino migration service. If your
estate is bigger than one database — most are — start with the assessment: usage measurement
across databases typically retires half the estate before anything is migrated at all.
Top comments (0)