OrgJiraMode

Last major edit (later minor edits)

Added:

> ----

Changed:

< Heads up - I noticed there is a problem if the description of the Jira item contains a "* Something" in it. This is used to create itemized list in Jira but org mode makes them headings, which get separated from the rest of the Jira item.

to

> THIS IS FIXED as of 1/28/2013 - I noticed there is a problem if the description of the Jira item contains a "* Something" in it. This is used to create itemized list in Jira but org mode makes them headings, which get separated from the rest of the Jira item.


1 Introduction

(For the latest verion of this page, visit this github page.

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) xml-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:

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.

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 whether the "/jira" at the end is 
;; necessary or not, see discussion at the end of this page

(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 .

Date: 2012-01-01 23:23:36 China Standard Time

Author:

Org version 7.7 with Emacs version 24

Validate XHTML 1.0

The jiralib-url should be set to your jira server home page without the “/secure/Dashboard.jspa" part. For e.g., after I login to APACHE jira server in Firefox, I am on "https://issues.apache.org/jira/secure/Dashboard.jspa", thus I should set the jiralib-url to "https://issues.apache.org/jira”.


Actually, there is another, fourth, way to use Jira without the browser, this is Atlassian command line interface. It doesn’t seem to be influenced by the limitations of xml-rpc or REST interfaces. Actually, I think the right Jira mode for Emacs should be built around this set of utilites. Being written in Java, the tools are a bit awkward and slow, but you can do anything with them, even some things not normally possible through web interface. - DmitriMinaev


THIS IS FIXED as of 1/28/2013 - I noticed there is a problem if the description of the Jira item contains a “* Something” in it. This is used to create itemized list in Jira but org mode makes them headings, which get separated from the rest of the Jira item.