Kanboard to Phabricator

A while ago KDE migrated our todo management from Kanboard to Phabricator to reduce the amount of software our System Administrators have to manage and maintain. In KDE neon we did this move already ahead of time so I happened to have a primitive migration script at hand, ultimately making me the person to auto migrate everyone’s todos.

Over the course of the migration, the script grew quite a bit in functionality and so I thought it may be useful to others and also to look at as an example for how to talk to the two systems. It’s no secret that I love having computers do all the work, so some nifty scripting goes a long way in making every day a happy day.

Fortunately, both systems feature a lovely REST API to easily grab data out of one and move it to the other. Kanboard uses JSON-RPC while Phabricator uses a largely RPC-like API (the API documentation is actually available in the conduit module of every Phabricator instance).

Particularly relevant API interfaces for moving would be:

Kanboard

• getAllTasks to get a list of all tasks on a project
• getAllComments to get a list of all comments on a

Phabricator

• maniphest.createtask to create tasks
• maniphest.edit to edit newly created tasks (this is actually an experimental interface, so it is still subject to change!)

To make things easy I simply hardcoded some stuff. Namely the id’s of projects in the respective systems, they don’t change and are easy enough to get via the web UIs.

You can have a look at the Ruby code over on Github.

It is fairly horrendous spaghetti but hopefully still readable enough to get the gist of it. The process itself is very straightforward.

1. Grab all tasks from Kanboard
2. Get all Comments of the tasks we want to migrate
3. Create new tasks in Phabricator
4. Edit the tasks to add comments. For simplicities sake, the code at hand simply re-creates the comments with a leading line mentioning the original author and time as obtained from Kanboard
5. One could do additional meddling at this point, such as tag additional projects, set priority etc. My script doesn’t do that since we wanted a very lightweight simple migration.
6. Remove the creating-user from subscribers (prevents the migrator from getting flooded with a million task notifications whenever someone does anything on Phabricator involving a task :))

Possibly the trickiest API endpoint to use is maniphest.edit. It is a very generic interface and when I created the script the documentation wasn’t overly clear either.

maniphest.edit is a transaction-based interface as you can see from the documentation. The payload sent to the endpoint describes which object to edit and which transactions to apply in which order. A Transaction is generally defining which action to carry out with which value. The value, in this case, is a variant dependent on the type of action.

Here’s an example payload for illustration

{
  "objectIdentifier": "PHID-TASK-xtokm64ym25mdvvbt3g4",
  "transactions": {
    "0": {
      "type": "comment",
      "value": "add a fancy comment"
    },
    "1": {
      "type": "subscribers.remove",
      "value": "PHID-USER-4kerus6xjnzeqjtp3t2k"
    }
  }
}

In this example, we’d be editing PHID-TASK-xtokm64ym25mdvvbt3g4 by first adding a comment and then unsubscribing PHID-USER-4kerus6xjnzeqjtp3t2k.
This is equal to doing the same combined changes in the web UI:

 

Of course, you could just as well only do one transaction at a time (that will, however, cause more mails/notifications to be sent; during a mass migration that hardly would matter though).

I hope this is helpful to someone 🙂