How (and Why) I Switched from JIRA to Clubhouse
My team of ~10-15 people had been using JIRA Cloud, the ticketing/project management system, for a few years, and I had grown to loath it (why?). Earlier this year I began considering alternatives in earnest, and came across Clubhouse.io via a Hacker News post.
Right off the bat, I was in love: it’s beautiful, modern, innovative, tailored to modern agile product development, and above all, FAST. (Oh, and it’s got a Clojure/Datomic backend too, which I think is neat!) Despite a proliferation of Kanban Klones, the most well-known being Trello, none of the options I looked at actually worked the way I wanted to work: hierarchical project-epic-story organization, quick filtering, built-in smart Git integrations, etc.. This blog post is a great overview of why to switch to Clubhouse, but needs to be updated, since many of those ‘missing’ features have since been added. Clubhouse is rapidly and continuously releasing effective improvements, and seem to be passionate about creating a great tool with great customer service to boot. Oh, AND it’s free for up to 3 users, AND apparently completely free for qualifying nonprofits.
That being said, it was still a bit of an uphill battle switching: first I had to convince the rest of the management team that it was worthwhile, and then I’d have to figure out how to move our entire JIRA database and get everyone onboard.
I even made a quick Keynote specifically to describe why I wanted to switch to Clubhouse:
I’m happy to say that I finally did it—here’s how.
We have over 2000 JIRA tickets, most of which are now completed. I briefly considered starting with just a nice, clean blank slate, but there’s too much detail in current open tickets we would lose. Thankfully, I found an importer script, so I forked it and added a number of improvements (and got to learn Go while I was at it!)
First you’ll need a Clubhouse organization and an API Token. Once you’ve got your org set up, go to
https://app.clubhouse.io/[your_organization]/settings/account/api-tokens to create a token. Copy that and do
export CLUBHOUSE_API_TOKEN=asdflkjaseflkjdf in your terminal so the token will be ready to go.
Then you’ll need to export your JIRA tickets. The easiest (or least horrible) way to do this is to do an Issue Search for all the tickets you want to export, then click the “Download” button near the top right, then “Export XML”. Note: you can right click and “Save As…” right on that link, otherwise it’ll open the XML right there in your browser. Yes, thanks, JIRA.
Now that you’ve got your input file (in the same dir as the importer), you’ll need to create a “user mapping” JSON file (say,
userMap.json) that describes how you want to map JIRA users to Clubhouse projects and User IDs. This looks like:
If you open up your JIRA export XML file, you’ll see elements like:
The importer uses only the
username attribute, so make sure you use those in your
Since you may want to assign projects by user, you can put the project IDs in as such. If you only have one Clubhouse project, just put that ID in for every user. To obtain your Clubhouse project IDs, you can do:
curl -X GET \
-H "Content-Type: application/json" \
-L "https://api.clubhouse.io/api/v1/projects?token=$CLUBHOUSE_API_TOKEN" | python -m json.tool > projects.json
Then look in that output file for the Project IDs.
Similarly, to obtain Clubhouse User IDs, you can do:
curl -X GET -H "Content-Type: application/json" -L "https://api.clubhouse.io/api/v1/users?token=$CLUBHOUSE_API_TOKEN" | python -m json.tool > users.json
Lastly, you need to setup your workflow mappings, i.e. JIRA “Selected for Development” -> Clubhouse “Selected for Sprint” or however you want it. To obtain your Clubhouse workflow state IDs, do:
curl -X GET \
-H "Content-Type: application/json" \
Right now the workflow mapping is only done in the script (no external config file, sorry!), so you’ll need to go to
jiraStructs.go and update this switch statement with your Clubhouse state IDs:
Pull the Trigger
OK, on to the main event: using the importer. With your
userMap.json file ready, do:
go run *.go import --in SearchRequest.xml --map userMap.json --token $CLUBHOUSE_API_TOKEN --test
This will run the tool in test mode, which will parse all the input files and show you what it’s going to do, but won’t upload data to Clubhouse. Once you’re satisfied, run the tool without the test flag, open up your Clubhouse workspace and watch those tickets roll in!
Also included are a few utility scripts in Python: createTestStory.py, deleteArchivedStories.py and deleteEmptyEpics.py. Use these like so:
python deleteArchivedStories.py $CLUBHOUSE_API_TOKEN
The importer will add a “JIRA” label to every ticket it imports. If something gets messed up and you need to redo an import, this makes it easy to select all imported tickets, archive them and use the above command to delete them.
If you’ve got a team of more than a few people, you’ll probably want to schedule a day to do the import and transition, so that they can stop updating JIRA tickets while you verify the import. Then you can do a little team meeting and show off your slick new interface!
Make sure to read the README for full details and create a Github issue if you run into any problems!