Blog

Converting a trac wiki to Confluence

We wanted to migrate our self-hosted trac wiki to Confluence, hosted by Atlassian (the makers of Confluence). There is a tool called the UWC (Universal Wiki Converter) that can help us.

First we need our trac data in a format that the UWC can process.

Export your wiki pages using the `trac-admin` utility that is installed when trac was installed:

trac-admin /path/to/your/trac/installation wiki dump /path/where/you/want/export/to/go

For example:

/opt/trac/bin/trac-admin /var/www/trac wiki dump /home/tom/tracwikidump_3Jul14

To export the attachments, there isn’t a suitable tool in trac v1.0 so I wrote a script to export each attachment that exists in the trac database:

php /home/tom/tracExportAttachments.php

Where tracExportAttachments.php is:

/**
* This script looks at the attachments in the trac database and exports each one in turn
* to create a folder structure that the UWC (Universal Wiki Converter) can understand.
*
* Prerequisites: sudo apt-get install php5-cli php5-mysql
*/
$DBServer = 'yourdbhost'; // e.g 'localhost' or '192.168.1.100'
$DBUser = 'youruser';
$DBPass = 'yourpassword';
$DBName = 'trac';
$destination_folder = '/home/tom/trac-attachments';
$conn = new mysqli($DBServer, $DBUser, $DBPass, $DBName);
if ($conn->connect_error) {
 trigger_error('Database connection failed: ' . $conn->connect_error, E_USER_ERROR);
}
$sql = "SELECT id,filename FROM attachment where type='wiki'";
$rs=$conn->query($sql);
if($rs === false) {
 trigger_error('Wrong SQL: ' . $sql . ' Error: ' . $conn->error, E_USER_ERROR);
} else {
 $i=1;
 while($row = $rs->fetch_assoc()) {
 $id = $row['id'];
 $name = escapeshellarg($row['filename']);
 $destination_folder2 = $destination_folder.'/'.$row['id'];
 if (!file_exists($destination_folder2)) {
 mkdir($destination_folder2);
 }
 $destination = escapeshellarg($destination_folder2.'/'.$row['filename']);
 $command = "/opt/trac/bin/trac-admin /var/www/trac attachment export wiki:".$id." ".$name." ".$destination;
 echo $i++." Running '".$command."'\n";
 echo shell_exec($command);
 echo "\n";
 }
 echo "DONE. {$i} attachments exported.\n";
}

Download the UWC (Universal Wiki Converter) tool from https://marketplace.atlassian.com/plugins/com.atlassian.uwc .
Activate XML RPC on confluence. See Administration -> General Configuration -> Remote API (XML-RPC & SOAP)
Unzip the UCW and launch the tool.

unzip uwc-4.0.zip
cd uwc
chmod +x *.sh
./run_uwc.sh

(Help shows the version I was running to be 4. The changelog only goes to 3.13)
Configure the tool:

  • Select type “trac”
  • Set the attachments directory to where the Attachments were exported from the script above.
  • Add all files you have exported.
  • Address that I used: https://peopleperhour.atlassian.net/wiki
  • Space Key that I used: PA – I found this from the “Space Permissions” page in Confluence. They seem to abbreviate the full space names to a few letters.

The tool gives a button to press to test the connection to confluence is working. I had a problem with SSL, which I fixed by editing conf/confluenceSettings.properties and set trustall=true ( see https://migrations.atlassian.net/wiki/display/UWC/UWC+SSL+Support ).
Universal Wiki Converter 4.0_007

I found the converter to fail on some pages that have specific syntax in them. Here’s some examples of things I found it didn’t like:

{{{blah.*}}}
{{{/{type}/{ownerId}/{id}.{ext}}}}
When a {{{ block is indented by any number of spaces
{{{‘List:---[]’}}}
some urls, e.g. https://cms.paypal.com/us/cgi-bin/?cmd=_render-content&content_ID=developer
When the bold and italics form too many single-quotes, e.g. '''It means our URLs don't need to end in ''.php'''''
strikethroughs: ~~[wiki:recommendations]~~

We had 419 trac pages and 171 attachments. About 20 pages had conversion errors. I fixed each case manually – although I wish I had had time to dig into the UWC sourcecode to fix the conversion errors.

Resources:

  • UWC Quickstart guide: https://migrations.atlassian.net/wiki/display/UWC/UWC+Quick+Start
  • Prepare trac: ( https://migrations.atlassian.net/wiki/display/UWC/UWC+Trac+Notes )
  • How to view a trac attachment:
    trac-admin /var/www/trac attachment list :
    e.g.
    /opt/trac/bin/trac-admin /var/www/trac attachment list wiki:AWSSetup
    

Update: A few weeks into using the new confluence wiki rather than trac and I have noticed more and more formatting issues. In hindsight I wish I had spent more time learning the migration method and maybe writing a plugin to fix formatting issues in the migration. The manual work to fix them in confluence is ending up a real time sink.

10 Comments

  • Akash

    I am trying to Migrate Trac wiki to Confluence, I am struggling from scratch, Can anyone please help me how to generate the Export. We have Trac installed on Linux box. Please let me know where should i look for and from where am i supposed to fire these command.

    Please help me on this. it would be great help.

    Thanks,
    Akash

    Reply
    • Tom

      Hi Akash, When you installed trac, usually it comes with a utility command called `trac-admin` which will allow you to export. You ssh into the machine that is running trac and run: `trac-admin wiki dump `

      Reply
      • Akash

        Hi Tom,

        I am not trac user so my knowledge on Trac is minus zero, This system is owned by other business owner, Can you please let me know when i fire the command from Terminal where will the dump be stored, I need both Export of Pages as well as Attachments that could allow to migrate Trac wiki to Confluence.

        Thanks,
        Akash

        Reply
        • Tom

          Sorry Akash, you’ll have to research this yourself using available documentation.

          Reply
  • Akash

    Hi Tom,

    Thank You,

    Thanks & Regards,
    Akash

    Reply
  • Akash

    Hi Tom,

    I have successfullt exported all wiki pages from trac to local directory, I have attachments as well all the attachments were stored on some directory. for Eg: attachments/..

    All Attachments are stored in respective directory.

    I am facing issue while exporting these into Confluence i am getting error as :
    No attachment found:

    Reply
  • Alex

    Hi,

    Thanks for the information but where is the code for tracExportAttachments.php?

    Reply
    • phenomenon

      Alex, here: confluence.atlassian.com/download/attachments/689014127/exportTrac.php

      Reply
    • Tom

      Hmm, It went missing, thanks for pointing it out Alex. I’ve added the tracExportAttachments.php script back now

      Reply
  • Tomas

    Hey,
    we you able to successfully migrate also the change history? Does ‘who’, ‘when’ and ‘what changed’ properly appear in Confluence for the migrated records?
    (We need to migrate from Trac and I’m looking for a suitable alternative.)

    Reply

Post A Comment