Jira 5 API Gem

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

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.

Using the API Gem in your application

The JiraApi 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. These two pieces of information are applied globally to your application, with separate JiraApi::Client objects created on a per-user basis.

An example initializer which sets the key and certificate filename in a pair of globals is shown below, myapp/config/initializers/jira_api.rb:

$CONSUMER_KEY = 'cbaec507669c65979b6b6eefdb1c5bb0' #Your consumer key. Can be generated by rake jira_api:generate_public_cert 
$PUBLIC_CERT_FILE = 'rsakey.pem' #Location of the Private Key File (generated by rake jira_api:generate_public_cert

This allows acces to the variables when a session is being set up. The following sample controller shows how to set up and initialize an access token for a particular user session. (Note that the callback url is defined in the Jira application link interface, and can be placed wherever suits you best in your application. The session#callback method is simply an example)

#TODO cannot pass params hash straight into init_access_token method - errors with a missing parameter exception

class SessionsController < ApplicationController
  def create
    session[:client] = JiraApi::Client.new($CONSUMER_KEY, '', :private_key_file => $PUBLIC_CERT_FILE)
    session[:request_token] = session[:client].request_token #Generate the request token
    redirect_to session[:request_token].authorize_url   #Redirect to Jira to authorize the token
  end

  def callback
    session[:client].init_access_token(:oauth_verifier => params[:oauth_verifier]) #Initialize the access token
    redirect_to root_url  #Redirect to the desired page after initializing the access token
  end
end