Most CCMS migration plans treat conversion as the finish line — valid DITA on disk, job done. Then the package meets the component content management system, the import gate rejects it, and the real project starts. This guide covers the last mile that migrations actually fail on: conformance to the schema your platform enforces, the map and folder structure it expects, ID and filename conventions, conref and keyref integrity, asset foldering, the metadata it indexes on, and validating all of it before import rather than after rejection.
There are two very different definitions of "done" in a migration project, and confusing them is the single most reliable way to blow a schedule. The conversion definition: legacy source in, valid DITA out, files delivered. The acceptance definition: the content is inside the CCMS, valid against the schema that system enforces, organized so authors can find and check out a topic, with reuse and cross-references resolving, images rendering, and metadata populated so search and filtering work.
Everything between those two definitions is the import gate, and it is unforgiving in a specific way: it fails late, in bulk, and usually silently. An import can succeed and still leave you with a flat folder of thousands of topics nobody can navigate, reuse flattened into literal text, or a search index that returns nothing because the elements the platform keys on were never written. Plan the migration so acceptance is the deliverable and the gate stops being a surprise.
The checklist below applies whether you are planning a Heretto migration, a Paligo migration, an IXIASOFT migration, a Tridion Docs migration, or an import into an in-house repository. We name those as target systems only — every platform publishes its own import specification, and that specification, not a generic DITA export, is what you are converting toward.
Every CCMS runs a version of the same gate. The vendor names differ; the failure modes do not. The important column in this table is the third one: nearly every failure has to be fixed upstream in the conversion, because fixing it inside the CCMS means hand-editing content that is already checked in, already versioned, and already assigned to authors.
| What the gate checks | How it fails | Where the fix belongs |
|---|---|---|
| Well-formedness and DTD or schema validity | Import aborts on the first bad file, or refuses the batch wholesale | In the conversion, proved by a validation pass before you submit anything |
| Specialization conformance | Topics import as generic types; specialized elements are stripped or refused | Element mapping written against your DTD, not a stock one |
| Map and folder structure | Content lands flat, or in a hierarchy that does not match how authors work | Decided at conversion time: topic-per-file or composite, submaps, subfolders |
| IDs and filenames | Collisions, silent renames, deep links from other systems going dead | ID and filename conventions applied during conversion |
| conref integrity | Reuse arrives as broken pointers, or is quietly resolved to flat text | A deliberate decision about reuse before volume, then validated |
| keyref and key scope | Unresolved keys, empty link text, keys colliding across publications | A generated key map per publication, scoped to that key space |
| Image and asset references | Missing-image placeholders discovered after go-live | Asset foldering with every reference rewritten to match |
| Metadata | Content imports fine and is then invisible to search and filters | Your metadata model written into topic prologs at conversion time |
A generic conversion produces valid, well-formed DITA with inferred structure. That is a legitimate starting point and a perfectly good outcome for some projects — but it uses generic topic types, generic element mapping, generated IDs and the source's own style names. A CCMS configured around a specialization will not accept that quietly.
A customer-specific DITA conversion maps to your specialization and your element rules instead: an authoring style named "Caution" becomes a real note of type caution rather than a paragraph that merely looks like one; conditional text becomes your ditaval and profiling scheme rather than a best guess; variables and reusable fragments resolve to match the reuse strategy your team actually uses. Because that tailoring is configuration rather than bespoke code written per project, a change of mind costs a re-run rather than a re-quote — which matters when the platform team revises a rule mid-migration, as they usually do. Full scoping of that work sits with our DITA migration services.
Get the DTD, the specialization and the element rules from the platform owner before conversion starts. If they do not exist yet, that is the first task on the plan, not a detail to settle after the first batch.
CCMS platforms differ sharply on whether they want one composite document per publication or a repository of individual topics governed by a bookmap. Both are legitimate targets, and moving between them is a routine DITA transformation rather than a re-conversion. Splitting a composite into properly typed topics plus a bookmap and a generated key map is covered in detail on composite DITA to split topics, including the choices your platform team will ask about: flat topic files or subfolders, a submap per chapter or a single governing map, and whether an ordered list in a body should become a task.
Once content is checked into a CCMS, its IDs are load-bearing. External systems deep-link to them, translation memory aligns on them, and release notes reference them. Decide before the first batch whether original source IDs are preserved or regenerated to a convention, and whether filenames derive from titles, from IDs, or from a numbering scheme. Then check for duplicates across the whole corpus, not per folder — duplicate IDs and duplicate keys are among the most common bulk-import rejections, and they only surface when the whole repository is validated together.
Reuse is the reason most teams move to a CCMS, and it is the thing migrations most often quietly destroy. Three decisions to make explicitly:
That last point is what Content Convergence does: identical topics, images and blocks are recognized as identical no matter where in the estate they live, collapsed to a single master, and every reference is rewritten to point at it — at a scale that comfortably covers the largest documentation estates. At deeper levels it also lifts repeated sections, tables, lists, steps and notes into a shared collection and replaces them with conrefs. Doing that before import means the CCMS receives a reuse repository rather than a pile of near-identical topics your authors will be asked to deduplicate by hand, forever.
Image and asset handling is unglamorous and disproportionately expensive to fix late. Every platform has an expected asset location — alongside the topic, in a media folder, or in a central library — and the reference inside the topic has to match it exactly after import, not before. Convert once into the target's layout instead of discovering the mismatch in a rendered PDF.
Metadata is the other silent failure. Content that imports cleanly but carries no indexable metadata is content your authors cannot find. Establish which prolog elements the platform indexes on — keywords, index terms, audience, product, component, lifecycle status — and populate them during conversion. Where the legacy source carries none, Knowledge Fabric can derive keywords from the content itself and write them into topic prologs, and every correction your subject experts make is retained as organizational knowledge that improves the next batch.
The cheapest gate is the one you run yourself. Before a single package goes near the platform, validate the whole repository against your schema and fix what it finds:
Our DITA completeness check runs exactly that list across the whole repository and returns a report your team can work from: one line per issue, each named with its severity, its file and line and what is wrong — so remediation is a work queue rather than an investigation. Run it on every batch — a full pass is fast enough to repeat after every round of fixes — and let errors fail the run, so a batch cannot be shipped while blocking issues remain.
Note the ordering constraint: the mapping stabilizes on a representative pilot, never on volume. Teams that start with volume end up re-running the whole corpus after every change of mind — which is survivable when re-running is mechanical, and ruinous when it is people.
Not every content management platform is DITA-native. Some are built on DocBook, and for those the path is a conversion into clean DITA followed by a DITA to DocBook transformation matched to what the destination expects. The rest of this guide still applies unchanged — schema conformance, structure, IDs, reuse, assets, metadata, validate before import — because the import gate is a property of content management, not of DITA.
Beyond converting legacy source into DITA, a CCMS migration means delivering content in the exact shape the target platform accepts: conformant to its DTD or specialization, in the map and folder structure it expects, with its ID and filename conventions, with conref and keyref reuse resolving inside the right key scopes, assets in the expected location with references rewritten, and the metadata the platform indexes on written into topic prologs. The project is done when the CCMS accepts and indexes the content, not when files are delivered.
The common causes are validity failures against your own schema rather than generic DITA, topics that do not conform to the platform's specialization, duplicate IDs or duplicate keys across the corpus, unresolved keyrefs and broken conrefs, image references pointing outside the package, and circular map chains. Each of these is detectable before import with a repository-wide validation pass, and each is far cheaper to fix in the conversion than in content already checked into the system.
Start by obtaining that platform's import specification — schema, expected map and folder layout, asset location, ID and filename rules, and required metadata — and convert toward that specification rather than toward generic DITA. Then run a representative pilot batch through the full path, import it, and turn everything the platform rejects into a change to the conversion before you process volume. DocentraX delivers output in exactly the structure the target platform expects; we name these systems only as migration targets.
Yes, and against your own schema. Pre-import validation should cover well-formedness, validity, broken links and cross-references, conref targets, keyref resolution, image and resource references, duplicate IDs and keys, and circular map chains. Our completeness check runs that list across the whole repository and reports each issue on one line with its severity, its file and line and what is wrong, which turns remediation into a work queue instead of an investigation.
Follow the target platform's convention, and treat it as a decision to make before conversion rather than after. The choices that matter are whether topics are delivered flat or in subfolders, whether a submap is generated per chapter or a single map governs everything, whether original source IDs are preserved or regenerated, and how filenames derive from titles, IDs or a numbering scheme. Once content is checked in, IDs become load-bearing for deep links and translation memory, so treat that choice as one-way.
It can, but only if reuse is a deliberate decision rather than a default. Decide explicitly whether conrefs are preserved as pointers or resolved into literal text, make sure keys resolve inside the key space of the publication that uses them so two products cannot collide, and establish single masters for duplicated topics and assets before import. Normalizing reuse before the content lands means the CCMS receives a reuse repository rather than near-duplicate topics your authors will be deduplicating by hand indefinitely.
We'll convert them to DITA free of charge — through the real pipeline, not a demo — and review the output with you. Then we'll discuss pricing one-to-one.
Request your free sample conversion