Instructions for migrating a Confluence wiki to IBM Connections

Relocate your Confluence wiki pages to the IBM Connections wiki

With developerWorks ending support of the Confluence wikis, teams and individuals that maintain pages there will need to migrate their data to the IBM Connections wiki. Instructions for doing so are presented in this article.

Share:

Jennifer Heins, Information Developer, IBM

Jennifer Heins is a Senior Software Engineer at IBM focusing on user adoption and collaborative information experience. She has been the driving force behind the Product Documentation wikis available for all IBM Collaboration Solutions and Lotus software products. Since joining IBM in 1998, Jennifer has worked tirelessly to advance how IBM delivers technical information, from standard information delivery to collaborative online sites. Her experiences with information architecture, mobile information, software architecture, and user interface design enable her to contribute to a variety of topics.



23 August 2012

Also available in Russian Japanese

Overview of migration

  1. Create a table of articles to migrate
  2. Prepare content prior to migration
  3. Migrate content
  4. Post-migration cleanup
  5. Redirect from Confluence to Connections article

Create a table of articles to migrate

Review all your articles in Confluence. Determine what action you want to take: migrate, leave alone, or delete. Depending on how many articles you have and how long you have had them, you might find that some are no longer relevant and can be removed and not migrated. Create a table that lists the articles and indicate what action you want to take.

Include columns in the table to keep track of migration tasks that you complete before and after migration. The remaining sections in this article guide you through these tasks and what you will put in the table as you go.

Table 1 shows a sample table for articles:

Table 1. Sample checklist
Article titlePrepare to migrateMigrateFix linksFix images/attachmentsRemove external link arrow iconsNotes/Status
Key concepts and termsMerge into new Overview topic 
  • Link to planning
  • Link to FAQ
No images In progress
       

Prepare content prior to migration

It is best to update or merge articles in Confluence before starting migration. At this stage you should focus on the content of the articles. Is the information still relevant, are there broken links, or do you want to merge articles. You can make these changes while all the articles are in one place relative to each other. Preparing ahead of time also means that when you start migration you only need to focus on migration tasks and not worry about the accuracy of the information.

Review your articles with the following points in mind:

  1. Ensure content is accurate and formatted the way you want on Confluence before migrating. Addressing formatting issues ahead of time lets you focus on migration specific tasks later.
  2. Rename pages before migrating. This will allow you to link more successfully between articles. Connections does not update links to an article if its title changes like Confluence does.
  3. Review links and confirm that you want them all. All links to migrated wiki articles will need to be updated after migration.
    • Update the table of articles with what links to update later. Put this in the Fix links column.
    • Links to external resources do not need to be updated.
  4. Remove automatic TOC links that appear on Confluence. These are anchor links that jump users down the page and there is no equivalent in the Connections wiki.
    • You can keep these links but each entry will need to be corrected after migration.
  5. Simplify content layout and styling as much as possible. Some formatting that was possible in Confluence might not be possible in the Connections wiki. All of the formatting will migrate but might need to be maintained using HTML, rather than wiki markup. The Connections wiki might not have equivalent wiki markup for everything you used in Confluence. Examples include:
    • Sections and columns - These come over as tables and would need to be managed as a table.
    • Styling, such as heading background coloring, that was set in an attached style sheet.
  6. Fix any links to peer wiki articles that show an external link icon. Links to peer wiki articles might have accidentally been created using the full URL to the article rather than just linking to the wiki article by title. In the Confluence wiki, any link that starts with http:// is marked as an external link and the external link icon appears. That external link icon will be migrated and you do not want that if the article is a peer and not external to the wiki. If you linked to another wiki article this way, clean it up now. To fix these, edit the article on Confluence and remove the full URL and only reference the article title. Here is an example:
    • Before: [Learn now to submit a request|http://www.example.com/wiki/Request+or+track+new+information]
    • After: [Learn now to submit a request|Request or track new information]

Migrate content

This process should take approximately 5 minutes per article. This also assumes you have a wiki created to hold the migrated articles.

  1. Create a new article, a "stub", in your Connections wiki and give it the title of the article you are migrating. Do not put in any content yet, or only put in "coming soon" as a place holder, and save the article. I recommend this for the following reasons:
    1. The article does not exist until you first save it. Once it is first saved, then auto-save will help ensure changes are not lost if something should happen in your browser.
    2. You can create many "stub" articles at this stage. This lets you focus on the navigation of the wiki articles first.
  2. Copy page from Confluence wiki:
    1. Go to page on Confluence. DO NOT go into edit mode.
    2. Select all text, including images, tables, etc., that you want to migrate and copy it. DO NOT copy any parts of the Confluence wiki user interface.
    3. DO NOT copy generated TOC at top of articles (unless you want to update those links). Or if you do copy the generated TOC, remove it during cleanup.
  3. Paste page in to Connections wiki:
    1. Locate the stub article in the Connections wiki.
    2. Go into Edit mode of the stub article.
    3. Paste the content in Rich Text.
    4. Briefly review the content but do not make many changes because it may look a little different after you save it. If you find that you copied too much or too little of the article don't waste time trying to fix it. Cancel the edit, copy the text again, and paste again.
  4. Click Save and Close.
  5. Make small updates as needed. Again, if many changes are needed, remove the entire content of the article and try again.
  6. When you have successfully migrated an article update the Migrate column in your table of articles.

Note: Content migrates over as simple HTML. You can see this by viewing HTML Source while in edit mode in Connections. More complex formatted wiki topics will have more complex HTML that might not be as easy to manage as it was in Confluence. This is simply because Connections does not have equivalent wiki markup for everything in Confluence.

On second look you might see additional changes you want to make before migrating. That is fine. Look over the page after you save it in Connections. If you see things you want to change, make the changes in Confluence and migrate the content again. To replace the content you already migrated, select all and delete, then paste the new content.


Post-migration cleanup

At this stage of migration you will be updating the articles in Connections. This process should take approximately 5 minutes per article.

  1. Fix links between wiki articles to point to the new articles in your Connections wiki.
    • DO NOT change links to pages that will remain on Confluence or are external to the Connections wiki.
    • Do this after you have migrated the article you are linking to so that you can locate the article on the Connections wiki.
    • Use the table of articles to keep track of what links need to update in each article. This will help you keep track of what is left to clean up.
    • To link to an article on the Connections wiki:
      1. Go into Edit mode.
      2. For an existing link, put your cursor on the link and click the link icon on the rich text editor or right-click to edit the link. For a new link, highlight the text you want to be the link and select the link icon in the rich text editor or right-click.
      3. Select the Wiki Page tab and locate the wiki article you want to link to.
      4. Scroll and page until you find the page you want to link to. As you work along, the newest wiki articles appear at the top of the list which makes finding them easy.
      5. Select the page and click OK.
  2. Remove automatic TOC links that appear on Confluence. These are anchor links that would have jumped the user down the page but they link back to the Confluence wiki. Either fix each link or remove them.
  3. Fix links to images and attachments. All the images that come over are referencing that image on Confluence.
    • Attach images to the Connections wiki article and link to it:
      1. Save images locally.
      2. Upload image to the article on the Connections wiki.
      3. Link to the attached image.
    • Attach attachments to the Conenctions wiki article and link to it:
      1. Save attachment locally.
      2. Upload attachment to the article on the Connections wiki.
      3. Link to the attachment.
  4. Remove external link arrow icons that might have come over when copied.
  5. Update the order of the navigation. The Connections wiki allows you to control the order of navigation entries. Change order of articles in the navigation.
    • Move page amongst peers.
      1. Go to the page you want to move.
      2. Select Page Actions > Move This Page.
      3. Go to Reorder Peer Pages and click the up or down arrows to move the page amongst its peers.
      4. Click Move when you are done.
    • Move page up or down a level in the navigation
      1. Go to the page you want to move.
      2. Select Page Actions > Move This Page.
      3. Go to Find Parent Page and click Browse to select a new parent for the page you want to move up or down.
      4. Click Move when you are done.

Redirect from Confluence to Connections article

You never know who has an article bookmarked. So to be safe add a link on the Confluence article to the new article on Connections.

  1. Update each article on Confluence as you finish migrating it.
  2. Edit the article on the Confluence wiki.
  3. Usign wiki markup, put the following wiki markup at the top of the page:

    {info:title=This information has moved}
    [This information has moved here|<link to topic in new wiki>]
    {info}

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into XML on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=XML
ArticleID=831798
ArticleTitle=Instructions for migrating a Confluence wiki to IBM Connections
publish-date=08232012