org-jira

1 Introduction

Org-mode is the best GTD (get things done) tool I have used. If you didn't use it, please consider give it a shot.

Jira is, well, a very popular Bug Tracking system. Two companies in a row where I worked chose Jira for bug tracking, task management, etc.

As an emacs enthusiast, I very much want to be able to use Jira within Emacs. Thus I started digging the web for a solution.

To use Jira without the browser, you can use a) xmp-rpc, b) soap, c) REST. I don't know what the last one is, but their supported degree by Jira is in ascending order. The former 2 protocols has both been supported by Emacs plugin: xml-rpc and soap.

For xml-rpc, there is already a jira.el, but it is not satisfactory for me:

  • xml-rpc is not as well supported as soap by Jira.
  • jira.el is a stand-alone tool, while I want to integrate with org-mode.

Luckily, the emacs-soap-client guy(s) already provided a sample jira2.el, so I started hacking by combining jira.el and jira2.el, the result is jiralib.el here (people suggested jira2.el is not a good name, as it can be quite confusing what the 2 means, and I totally agree, thus the name jiralib).

After browsing Jira with jira2.el is implemented, I checked org2blog for ideas of how to hack on org-mode, and started from his org2blog.el and hacked into a new org-jira.el.

2 Features

2.1 Sync Jira tickets into Org-mode todo items in a batch mode

Jira ticket attributes such as priority, status, resolution, summary, description, etc. are supported. New ones can be added if desired by hacking the elisp.

See the following example. Jira ticket summary has been used as the Org TODO headline; most Jira ticket attributes have been made into Org entry; Jira description attribute is made into a separate subtitle because unlike most attributes it is multi-line. 

* TODO test summary                                              :SANDBOX_22:
  :PROPERTIES:
  :assignee: hjbao
  :reporter: hjbao
  :type:     Bug
  :priority: Major
  :status:   Open
  :ID:       SANDBOX-22
  :END:

** description: SANDBOX-22
test description
** Comment: Bao Haojun
   :PROPERTIES:
   :ID:       21322
   :END:
test comment

Also note the ID Org entry, both the Jira issue and Jira comment has an attribute ideal for this entry. Org-mode has an API for finding heading from ID entry.

2.2 Update Org-mode new edits back to Jira

After you edit the attributes, such as change priority from "Major" to "Minor", you can post it back the Jira.

2.3 Progress Jira ticket workflow in Org-mode

You can Resolve/Close/Reopen the jira ticket and so on, without leaving org-mode!

2.4 Create new Jira issue in org mode

You can create new Jira issue within org mode. You will be prompted for Jira ticket information such as create in which project, assign to whom, and one-line summary, etc.

2.5 Convert existing org mode TODO item into Jira ticket

This one is similar to the create-new-issue case, except the existing TODO headline can be used for Jira ticket summary.

The old TODO is deleted. But you will not lose a TODO entry, instead, you will trade a normal TODO for a Jira ticket tracked TODO.

2.6 Edit existing Jira comments / add new comment

These are also supported.

2.7 Open current issue in browser

Last but not least, if you think org-jira can not perform some tasks you wanted, you can press a key combination (default "C-c i b") to open the current issue in an external browser such as firefox.

3 Usage

To use org-jira.el, get the .el files from org-jira on github. 

git clone git://github.com/baohaojun/org-jira.git

(In my repository, I have included the emacs-soap files, which you can get from its project, but in my version I fixed an utf-8 encoding bug in it so that I can post comments in Chinese).

Then put the following in your .emacs, 

(setq jiralib-url "http://jira-host/jira")
; you need make sure the jiralib-url is correct. Login your jira
; server in browser, the home page URL should be like:
; https://issues.apache.org/jira/secure/Dashboard.jspa
; remove the "/secure/Dashboard.jspa" part and you get the jiralib-url: 
; "https://issues.apache.org/jira"

(require 'org-jira)
; jiralib is not explicitly required, since org-jira will load it

(If you have a ~/.authinfo file and corresponding entry for jira-host, the username and password will be computed from that; or else you will be prompted for password).

Then start syncing with M-x org-jira-get-issues .