Field Guide
Moving From One CCMS to Another
Why Teams Move
Four Common Triggers
- The vendor changed, or the contract is ending
- An acquisition, a product sunset, or a renewal that no longer makes sense. The deadline is set by the contract, not by readiness.
- The content model outgrew the system
- A move from one topic model to another, or into a program that requires S1000D, can expose limits the old system never had to face.
- Review, output, or access no longer fit
- Reviewers who will not log in, publishing pipelines nobody can maintain, or access rules that cannot separate one audience from another.
- Several groups are consolidating
- Two libraries on two systems become one. This is a migration and a merge at the same time, and the merge is usually the harder part.
This guide is about moving from one system to another. Moving into structured content for the first time is a different job; see DITA migration, FrameMaker conversion, and convert or ingest.
What Has to Travel
More Than Topics
A file export gets the topics out. A working library is topics plus everything the system knew about them. Use this as the inventory list:
- Topics and their identifiers
- The obvious part. Check that file names, IDs, and any unique identifiers survive unchanged, because everything else points at them.
- Maps and publication definitions
- In DITA, the maps that assemble deliverables. In S1000D, the publication modules. Without them you have parts and no books.
- Keys, links, and content references
- Keys are defined at map level, and key scopes let different branches of a map use different definitions. Cross-references, key references, and conrefs all resolve through that structure, so they break quietly when maps or scopes move differently from topics.
- Metadata and taxonomy
- Properties, classification values, and controlled vocabularies. If the old system held them outside the files, they will not travel with a plain file export.
- Applicability and conditions
- Condition attributes and the filter files that apply them in DITA; applicability definitions in S1000D. A value the new system does not know silently filters content in or out.
- Version history and baselines
- Which revision went into which delivered publication. This is the item most often lost and most expensive to reconstruct. See the decision below.
- Branches
- Parallel work streams, such as a major edition and interim updates, only survive if the target models branching the same way. See the guide to document branching.
- Illustrations and other binaries
- Graphics, with their identifiers and revision lives, plus video, 3D, and attachments. Check the links in both directions: the topic to the graphic, and the graphic to the topics that use it.
- Translation memory and localized variants
- Translated topics, their link to the source revision, and the memory behind them. A translation that no longer knows which source it answers is a cost to redo.
- Workflow state, review comments, and the audit trail
- What is in review, who approved what, and the record of it. Programs with release or regulatory evidence requirements treat these as records, not conveniences.
- Rules and customizations
- Schemas and their constraints, and in S1000D the business rules data module (BREX). Customizations decide whether yesterday's valid content is still valid.
- Stylesheets and output pipelines
- The transforms and templates that turn source into PDF, HTML, or an interactive viewer. They are usually the least portable part. See how XML becomes a PDF.
- Users, roles, and permissions
- Who can see and change what. Rebuild these deliberately, especially where access is controlled by person or by marking.
The same list is the best test of a candidate system's exit terms, which is why the CCMS requirements checklist asks for an export of content, history, metadata, links, and illustrations in an open format.
Deciding What to Keep
Current Baseline or Full History?
Some things rarely survive intact: workflow state in flight, comments attached to a draft, the customizations of one vendor's review tool, and any metadata that lived only in the system's database. Decide, item by item, whether each one is moved, rebuilt, archived, or dropped.
Version history is the biggest decision. Moving only the current baseline is faster and cleaner, and the old system, or a verified export of it, stays available read-only for questions about the past. Moving the full history keeps one place to look, but it multiplies the volume and depends on the target modeling revisions the way the source did. Neither is right everywhere.
The test is the question you will be asked later. If a contract, a regulator, or a customer may ask what exactly you delivered on a given date, preserve the baselines that answer it, plus the review and approval records that go with them. If nobody will ever ask, the history is a cost. Read the text of your contract and your quality or regulatory obligations; do not assume. Dated deliverables are covered in effective-dated publishing, and parallel revisions in branching for documents.
Export Formats
What Comes Out of the Old System
For DITA content, the portable core is standard: topics, maps, and graphics as files, on a version of the specification both systems support. DITA 1.3 with Errata 02 is the current OASIS version. The non-portable part is the wrapper around it: workflow, metadata held in the repository, history, and permissions are specific to each system, and a package export may include some, all, or none of them. Ask for a real export of a real project and inspect what is missing.
For an S1000D repository, the content is more tightly specified: data modules carry identifiers, issue and in-work numbers, and applicability, and the specification defines how data modules and their supporting objects are exchanged between repositories. Programs, and government customers in particular, can add their own exchange requirements on top. Read the exchange rules in the issue your program cites, and see what a CSDB is and government-owned CSDBs. The specification itself is free to download from the S1000D user site.
Either way, test the export before you need it. A vendor-specific container that only its own system can read is the case you are trying to avoid, and the moment to find it is a trial, not cutover.
The Plan
Seven Phases
- 1. Inventory
- Count what exists, by content type and by family: topics, maps, graphics, translations, branches, and the metadata and rules around them. Note which content is active, which is archive, and which is duplicated.
- 2. Mapping
- For each item in the inventory, write where it lands in the target and what changes in transit: identifier schemes, metadata fields, condition values, roles. Anything with no home in the target is a decision, not a task.
- 3. Trial migration
- Move a deliberately awkward sample, including the most reused topics, the most heavily branched book, and a translated deliverable. Throw the result away and fix the mapping.
- 4. Validation
- Run the checks below on the trial, then again on every full load. Agree in advance what counts as a pass.
- 5. Parallel run
- Publish the same release from both systems and compare the outputs. Freeze or tightly control edits in the old system for the length of the run, or you are comparing a moving target.
- 6. Cutover
- Pick a quiet point in the release calendar, set a freeze date, load the final delta, repeat the checks, and tell authors exactly when the old system turns read-only.
- 7. Decommission
- Keep the old system read-only, or a verified export of it, until the first release from the new system is accepted and the retention question is settled. Then switch it off on purpose, not by lapse.
Validation
Checks to Run on Every Load
- Counts match: topics, maps, graphics, and translations in the source against the target, by content family.
- Every link resolves: topic to topic, topic to graphic, key to its definition, conref to its target, in both systems and with the same result.
- Keys and scopes resolve to the same values in every deliverable.
- Validation passes against the same schema, constraints, and, for S1000D, the same business rules, or the differences are listed and accepted.
- Conditions and applicability produce the same filtered content for each product, model, and audience.
- A sample of published outputs matches page for page, with an agreed list of acceptable differences.
- Revision history and baselines answer the question the program will actually ask: what did we deliver on this date?
- Permissions give each role the access it had, and no more, tested by logging in as that role.
- Translated content is still paired with the right source revision.
- A round trip works: export from the new system and confirm the export can be read without it.
Automate what can be automated, since a migration is loaded more than once. A human still has to open the awkward documents and read them.
FAQ
Questions We Hear
How long does a CCMS migration take?
It depends on the volume, the number of branches and languages, and how different the two content models are. The inventory and mapping phases give the first honest estimate, so ask for a date after the trial migration, not before.
Can we move DITA content between systems without conversion?
The topics and maps are standard XML, so they usually move as files. What does not move automatically is everything the system held around them: metadata stored outside the files, workflow and review state, version history, branches, and permissions. Plan for those separately.
Do we have to bring the full revision history?
Not always. If no contract, regulation, or audit requires it, a clean current baseline plus a verified read-only archive of the old system is often enough. If you must show what was delivered on a past date, the baselines matter even if the intermediate edits do not. Read your contract and your quality or regulatory obligations before deciding.
What is different when the system is an S1000D CSDB?
The content is already tied to data module identifiers, issue and in-work numbers, applicability, and business rules, so the move has less to invent and more to preserve. The specification defines how data modules and their supporting objects are exchanged between repositories, and the program can add its own rules. Read the exchange rules in the issue your program cites, and see our explainers on the CSDB and on government-owned repositories.
Should we clean up content before or during the move?
Before, where you can, and never silently during. Cleanup inside a migration makes validation ambiguous, because you cannot tell a loss from a deliberate deletion. Retire duplicates and dead content in the old system, record the decision, and then move what is left.
Get In Touch
Planning a Move Between Systems?
Tell us what is moving, which systems it is moving between, and what has to survive the trip.