A healthcare software company serving 150,000+ professionals was stuck on Confluence 3.x with 500,000+ pages of critical medical documentation, heavily customized code, modified database structures, and bespoke integrations. Vendors said a standard upgrade path wouldn't work. As project manager, I led the discovery, planning, and stakeholder communications that got it done – under budget and ahead of schedule.
The Challenge: Confluence 3.x with 500,000 Pages of Medical Documentation
In 2015, while working at Adaptavist, I was the project manager for a Confluence platform upgrade for a healthcare software company. The situation was, to put it plainly, a mess – but the kind of mess that accumulates through years of reasonable decisions rather than negligence.
The company used Confluence as the backbone of their documentation platform, serving over 150,000 healthcare professionals. These weren't casual wiki users browsing internal notes. These were doctors, nurses, pharmacists, and administrators relying on the platform for clinical reference material, procedural documentation, and regulatory compliance information. When I say the documentation was critical, I mean it in a way that most technology projects never have to contend with.
The Confluence instance held over 500,000 pages. That alone would make any upgrade complex. But the real complexity came from what had been done to the platform over the years.
Why This Confluence 3.x Instance Couldn't Follow a Standard Upgrade Path
Confluence 3.x was old. By 2015, Atlassian had released several major versions, and the gap between 3.x and the target version wasn't just a number – it represented fundamental changes to the platform's architecture, plugin framework, and data model.
Under normal circumstances, Atlassian provides upgrade guides and migration tools that handle the transition. But this instance wasn't normal by any definition.
Heavily Customized Confluence Code
The client's technical team had extensively modified Confluence's codebase over the years. When the platform didn't do what they needed, they made it do what they needed. Custom macros, modified rendering pipelines, altered page handling – the kind of deep modifications that make the software more useful and simultaneously make it harder to maintain.
Each customization was a reasonable decision at the time. A healthcare documentation platform has requirements that a general-purpose wiki doesn't anticipate. But each customization also created a dependency on specific internal behaviors of Confluence 3.x – behaviors that might change or disappear in later versions.
Modified Database Structures
Beyond the application code, the database itself had been modified. Additional tables, altered schemas, custom indexes – changes made to support the platform's specialized healthcare use cases. A standard Confluence upgrade expects a standard Confluence database. This database was anything but standard.
Database modifications are particularly risky during upgrades because migration scripts assume specific starting conditions. When those assumptions don't hold, migrations can fail silently – appearing to complete successfully while actually corrupting data in ways that only surface weeks or months later. With 500,000 pages of medical documentation, that risk was unacceptable.
Customized Marketplace Plugins
The platform also included Confluence plugins from marketplace vendors that the client had then modified. We weren't just dealing with a wiki upgrade – we had to upgrade to newer versions of plugins that had been customized beyond what the vendors built. The vendors weren't going to support that. We had good conversations with them and they tried to be as helpful as they could, but their plugins had been modified to work with this custom system, and there wasn't much they could do to help us upgrade the modified versions.
When Vendors Say It Can't Be Done
Before I got involved, the client had approached vendors – including Atlassian – about the upgrade. The consensus was that the standard upgrade path wouldn't work for this instance. The customizations were too deep, the database modifications too extensive, the integrations too fragile. Nobody was willing to guarantee a clean upgrade, and several vendors recommended rebuilding from scratch – a proposal that would have been enormously expensive and disruptive.
That's the context I walked into. A platform that needed to be upgraded, an upgrade that conventional wisdom said couldn't be done conventionally, and 150,000 healthcare professionals depending on the system staying functional throughout.
Discovery Phase: Documenting a Decade of Confluence Customization
Before I could plan the upgrade, I needed to understand exactly what had been built. The documentation on the customizations was incomplete – another common pattern in long-running systems where the people who made the changes have moved on and the institutional knowledge lives in the code rather than in any written record.
Mapping Confluence Code Modifications and Dependencies
The first phase involved a thorough archaeological survey of the codebase. A consultant from Adaptavist conducted the detailed code and database analysis – every custom modification needed to be identified, documented, and analyzed for its compatibility with the target Confluence version. This meant reading through code changes, talking with the client's developers who had the most history with the system, and cross-referencing against Atlassian's upgrade documentation to flag the places where custom code would conflict with platform changes.
I managed the project, helped the consultant work through the analysis, handled all estimation and planning, and managed all communications with the client's stakeholders so the consultant could focus on the technical work. I also handled all communications with both Atlassian and the marketplace plugin vendors.
This wasn't exciting work. It was meticulous, sometimes tedious, and absolutely essential. Skipping this step or doing it superficially is how upgrade projects fail. The modifications you don't know about are the ones that break things in production.
Cataloging Database Schema Changes
The database analysis followed a similar pattern. The consultant compared the actual database schema against a clean Confluence 3.x schema to identify every modification – added columns, new tables, altered constraints, custom stored procedures. Each difference was documented and categorized by risk level: modifications that would need to be preserved through the upgrade, modifications that could be refactored into supported extension points, and modifications that could be retired.
Collaborative Problem-Solving with the Client's Technical Team and Atlassian
Discovery is only useful if it leads to a plan. And this plan needed to be developed collaboratively – I couldn't dictate an upgrade approach without deep involvement from both the client's technical team and Atlassian's own experts.
Working with the Client's Development Team
The client's developers knew things about their system that no external consultant could learn in weeks. They understood the business context behind each customization – why it existed, who depended on it, and what would break if it changed.
I led the in-person discovery sessions and estimation and planning sessions with the client's team in Kansas City, Missouri. The Adaptavist consultant was based in London and couldn't travel, so these sessions were conducted solo by me. The consultant was typically on calls but not always present. I worked through the customization inventory with the client's developers, categorizing each modification by upgrade approach: migrate as-is, refactor to use supported APIs, replace with existing plugins, or retire. Some decisions were straightforward. Others required extensive discussion about tradeoffs between preservation effort and long-term maintainability.
The Role of Atlassian's Technical Account Manager
The client had paid for a Technical Account Manager (TAM) from Atlassian, and he was a helpful connection point – he's actually the one who recommended Adaptavist to solve this because Atlassian couldn't figure it out themselves. But the TAM didn't have the depth of knowledge about Atlassian's internals that we had at Adaptavist. Atlassian did not provide engineering support or deep technical insight for this engagement. The expertise came from our side.
Building the Comprehensive Confluence Upgrade Runbook
All of the discovery and collaborative planning culminated in a comprehensive upgrade runbook – a detailed, step-by-step document that specified every action required to move the platform from Confluence 3.x to the target version.
Sequenced Upgrade Steps with Rollback Procedures
The runbook wasn't just a list of commands. Each step included preconditions (what needed to be true before executing), the action itself, verification criteria (how to confirm the step succeeded), and rollback procedures (how to reverse the step if verification failed). With 500,000 pages of medical documentation at stake, every step needed a safety net.
The sequencing was critical. Database modifications needed to happen in a specific order relative to application upgrades. Custom code migrations had dependencies on both. Integration updates had to be timed to avoid downstream disruption. Getting the sequence wrong could leave the system in an inconsistent state that was harder to fix than the original problem.
Testing Strategy for Healthcare Confluence Migration
We built a staging environment that replicated the production system as closely as possible – same data volume, same customizations, same integrations. The runbook was executed against this environment multiple times, each iteration uncovering issues that refined the plan.
Testing with 500,000 pages of real data (appropriately anonymized) was non-negotiable. Performance characteristics at that scale differ meaningfully from smaller test datasets. A migration step that completes in minutes against 10,000 pages might take hours against 500,000 – and that timing affects the entire upgrade window and rollback strategy.
Delivered Under Budget, Ahead of Schedule
The upgrade succeeded. It came in under budget and ahead of schedule.
I want to unpack why, because "under budget and ahead of schedule" sounds like a project management cliche. In this case, it was the direct result of investing heavily in discovery upfront. The discovery phase consumed more time and budget than some stakeholders initially expected, and I had to make the case that thorough preparation would pay for itself during execution.
It did. The execution phase went smoothly because we'd already found and planned for the problems. There were no surprise customizations discovered at 2 AM during the migration window. No database modifications that conflicted with migration scripts in unexpected ways. No integrations that broke because someone forgot they existed. The runbook worked because the discovery was thorough.
Enabling Independent Confluence Maintenance for the Client
One outcome I'm particularly proud of is that the client gained the capability for independent future maintenance. The discovery documentation, upgrade runbook, and collaborative process we followed didn't just serve the immediate upgrade – they created a body of knowledge that the client's team could use going forward.
Before this project, the client's relationship with their Confluence platform was one of learned helplessness. The customizations had created a system that felt too complex and fragile to touch. The upgrade process demystified it. The client's developers came out of the project with a clear understanding of every modification in their system, why it existed, and how it interacted with the platform.
That knowledge transfer wasn't a bolt-on deliverable. It was built into the process. By collaborating closely with the client's team throughout discovery and planning, the learning happened organically. When the project ended, they didn't need another consultant to maintain their system – they understood it themselves.
Frequently Asked Questions
Is it possible to upgrade a heavily customized Confluence 3.x instance?
Yes, but not through the standard upgrade path. Heavily customized instances require thorough discovery of all modifications (code, database, integrations), collaborative planning with both the internal team and Atlassian, and a comprehensive runbook with rollback procedures for every step. The key is investing in discovery. Vendors who say "it can't be done" usually mean "it can't be done with our standard process" – which is true but doesn't mean custom processes can't work.
How do you handle 500,000+ pages during a Confluence migration?
Scale affects everything: migration timing, testing strategy, rollback feasibility, and performance validation. You need a staging environment with production-scale data to get accurate timing estimates. You need to understand which migration steps are linear (time scales proportionally with page count) versus which have non-linear behavior at scale. And you need a realistic assessment of your maintenance window – if the migration takes longer than expected, do you have enough time to complete it or roll back before the system needs to be available again?
What should healthcare organizations consider when upgrading Confluence?
Healthcare adds regulatory and operational constraints. Data integrity is paramount – medical documentation errors can affect patient care. Compliance requirements (like HIPAA in the US) affect how you handle data during migration, who has access to staging environments, and how you document the process for audit purposes. And downtime planning needs to account for the fact that healthcare professionals may need access to documentation outside of normal business hours. I recommend scheduling migration windows during the lowest-usage periods and having offline reference materials available as a fallback.
Related Case Studies
- Atlassian Implementation for a Health Insurance Startup: From 100 to 30,000 Members – Another healthcare Atlassian project, focused on building new systems rather than upgrading existing ones.
- Unifying Documentation for 25+ Atlassian Apps in Confluence – Large-scale Confluence documentation work, with a different set of challenges around content consolidation.
- Defining Product Strategy for the Adaptavist Library – An example of using structured discovery (stakeholder interviews, Wardley Mapping) to bring clarity to an uncertain situation – the same discovery-first principle applied here.