JIRA 5 API Gem

This gem provides access to the Atlassian JIRA version 5 REST API (a.k.a REST API version 2).

My changes on transitions

Pull request on sumoheavy's repo: https://github.com/sumoheavy/jira-ruby/pull/48 This allows the application of transitions on issues. It does not have any working tests, so I don't expect it to be accepted. However, if you would like to write some, be my guest. I will be using my fork internally, and I will hopefully get around to testing this code soon.

Example usage:

# issue = a jira-ruby issue
transition = issue.transitions.build()
trans_response = transition.save(:transition => {:id => 51})

Example usage

client = JIRA::Client.new({:consumer_key => CONSUMER_KEY, :consumer_secret => CONSUMER_SECRET})

project = client.Project.find('SAMPLEPROJECT')

project.issues.each do |issue|
puts "#{issue.id} - #{issue.summary}"
end

issue.comments.each {|comment| ... }

comment = issue.comments.build
comment.save({'body':'My new comment'})
comment.delete

Links to JIRA REST API documentation

• Overview
• Reference

Setting up the JIRA SDK

On Mac OS,

brew install atlassian-plugin-sdk

Otherwise:

• Download the SDK from https://developer.atlassian.com/ (You will need an Atlassian login for this)

• Unpack the dowloaded archive

• From within the archive directory, run:

  ./bin/atlas-run-standalone --product jira --version 5.0-rc2
  

Once this is running, you should be able to connect to http://localhost:2990/ and login to the JIRA admin system using admin:admin

You'll need to create a dummy project and probably some issues to test using this library.

Configuring JIRA to use OAuth

From the JIRA API tutorial

The first step is to register a new consumer in JIRA. This is done through
the Application Links administration screens in JIRA. Create a new
Application Link.
{Administration/Plugins/Application Links}[http://localhost:2990/jira/plugins/servlet/applinks/listApplicationLinks]

When creating the Application Link use a placeholder URL or the correct URL
to your client (e.g. `http://localhost:3000`), if your client can be reached
via HTTP and choose the Generic Application type. After this Application Link
has been created, edit the configuration and go to the incoming
authentication configuration screen and select OAuth. Enter in this the
public key and the consumer key which your client will use when making
requests to JIRA.

This public key and consumer key will need to be generated by the Gem user, using OpenSSL or similar to generate the public key and the provided rake task to generate the consumer key.

After you have entered all the information click OK and ensure OAuth authentication is
enabled.

Configuring JIRA to use HTTP Basic Auth

Follow the same steps described above to set up a new Application Link in JIRA, however there is no need to set up any "incoming authentication" as this defaults to HTTP Basic Auth.

Using the API Gem in a command line application

Using HTTP Basic Authentication, configure and connect a client to your instance of JIRA.

require 'rubygems'
require 'pp'
require 'jira'

# Consider the use of :use_ssl and :ssl_verify_mode options if running locally 
# for tests.

username = "myremoteuser"
password = "myuserspassword"

options = {
          :username => username,
          :password => password,
          :site     => 'http://localhost:8080/',
          :context_path => '/myjira',
          :auth_type => :basic
        }

client = JIRA::Client.new(options)

# Show all projects
projects = client.Project.all

projects.each do |project|
puts "Project -> key: #{project.key}, name: #{project.name}"
end

Using the API Gem in your Rails application

Using oauth, the gem requires the consumer key and public certificate file (which are generated in their respective rake tasks) to initialize an access token for using the JIRA API.

Note that currently the rake task which generates the public certificate requires OpenSSL to be installed on the machine.

Below is an example for setting up a rails application for OAuth authorization.

Ensure the JIRA gem is loaded correctly

# Gemfile
...
gem 'jira-ruby', :require => 'jira'
...

Add common methods to your application controller and ensure access token errors are handled gracefully

# app/controllers/application_controller.rb
class ApplicationController < ActionController::Base
protect_from_forgery

rescue_from JIRA::OauthClient::UninitializedAccessTokenError do
  redirect_to new_jira_session_url
end

private

def get_jira_client
  
  # add any extra configuration options for your instance of JIRA,
  # e.g. :use_ssl, :ssl_verify_mode, :context_path, :site
  options = {
    :private_key_file => "rsakey.pem",
    :consumer_key => 'test'
  }

  @jira_client = JIRA::Client.new(options)

  # Add AccessToken if authorised previously.
  if session[:jira_auth]
    @jira_client.set_access_token(
      session[:jira_auth][:access_token],
      session[:jira_auth][:access_key]
    )
  end
end
end

Create a controller for handling the OAuth conversation.

# app/controllers/jira_sessions_controller.rb
class JiraSessionsController < ApplicationController

before_filter :get_jira_client

def new
  request_token = @jira_client.request_token
  session[:request_token] = request_token.token
  session[:request_secret] = request_token.secret

  redirect_to request_token.authorize_url
end

def authorize
  request_token = @jira_client.set_request_token(
    session[:request_token], session[:request_secret]
  )
  access_token = @jira_client.init_access_token(
    :oauth_verifier => params[:oauth_verifier]
  )

  session[:jira_auth] = {
    :access_token => access_token.token,
    :access_key => access_token.secret
  }

  session.delete(:request_token)
  session.delete(:request_secret)

  redirect_to projects_path
end

def destroy
  session.data.delete(:jira_auth)
end
end

Create your own controllers for the JIRA resources you wish to access.

# app/controllers/issues_controller.rb
class IssuesController < ApplicationController
before_filter :get_jira_client
def index
  @issues = @jira_client.Issue.all
end

def show
  @issue = @jira_client.Issue.find(params[:id])
end
end

Using the API Gem in your Sinatra application

Here's the same example as a Sinatra application:

require 'jira'
class App < Sinatra::Base
enable :sessions

# This section gets called before every request. Here, we set up the
# OAuth consumer details including the consumer key, private key,
# site uri, and the request token, access token, and authorize paths
before do
  options = {
    :site               => 'http://localhost:2990',
    :context_path       => '/jira',
    :signature_method   => 'RSA-SHA1',
    :request_token_path => "/plugins/servlet/oauth/request-token",
    :authorize_path     => "/plugins/servlet/oauth/authorize",
    :access_token_path  => "/plugins/servlet/oauth/access-token",
    :private_key_file   => "rsakey.pem",
    :rest_base_path     => "/rest/api/2",
    :consumer_key       => "jira-ruby-example"
  }

  @jira_client = JIRA::Client.new(options)
  @jira_client.consumer.http.set_debug_output($stderr)

  # Add AccessToken if authorised previously.
  if session[:jira_auth]
    @jira_client.set_access_token(
      session[:jira_auth][:access_token],
      session[:jira_auth][:access_key]
    )
  end
end


# Starting point: http://<yourserver>/
# This will serve up a login link if you're not logged in. If you are, it'll show some user info and a
# signout link
get '/' do
  if !session[:jira_auth]
    # not logged in
    <<-eos
      <h1>jira-ruby (JIRA 5 Ruby Gem) demo </h1>You're not signed in. Why don't you 
      <a href=/signin>sign in</a> first.
    eos
  else
    #logged in
    @issues = @jira_client.Issue.all

    # HTTP response inlined with bind data below...
    <<-eos
      You're now signed in. There #{@issues.count == 1 ? "is" : "are"} #{@issues.count} 
      issue#{@issues.count == 1 ? "" : "s"} in this JIRA instance. <a href='/signout'>Signout</a>
    eos
  end
end

# http://<yourserver>/signin
# Initiates the OAuth dance by first requesting a token then redirecting to 
# http://<yourserver>/auth to get the @access_token
get '/signin' do
  request_token = @jira_client.request_token
  session[:request_token] = request_token.token
  session[:request_secret] = request_token.secret

  redirect request_token.authorize_url    
end

# http://<yourserver>/callback
# Retrieves the @access_token then stores it inside a session cookie. In a real app, 
# you'll want to persist the token in a datastore associated with the user.
get "/callback/" do
  request_token = @jira_client.set_request_token(
    session[:request_token], session[:request_secret]
  )
  access_token = @jira_client.init_access_token(
    :oauth_verifier => params[:oauth_verifier]
  )

  session[:jira_auth] = {
    :access_token => access_token.token,
    :access_key => access_token.secret
  }

  session.delete(:request_token)
  session.delete(:request_secret)

  redirect "/"
end

# http://<yourserver>/signout
# Expires the session
get "/signout" do
  session.delete(:jira_auth)
  redirect "/"
end
end