JOT 1.0.2

data/Gemfile

@@ -0,0 +1,14 @@
+source "http://rubygems.org"
+# Add dependencies required to use your gem here.
+# Example:
+#   gem "activesupport", ">= 2.3.5"
+gem "soap4r", ">= 1.5.8"
+
+# Add dependencies to develop your gem here.
+# Include everything needed to run rake, tests, features, etc.
+group :development do
+  gem "shoulda", ">= 0"
+  gem "bundler", "~> 1.0.0"
+  gem "jeweler", "~> 1.6.4"
+  gem "rcov", ">= 0"
+end

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2011 Darrin Mison
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,61 @@
+# ABOUT
+This is a fairly simple Ruby script that uses SOAP to retrieve issues from a JIRA instance and pumps them into
+a customizable ERB template.
+
+# TESTED ON
+
+* Ruby 1.8.7 on Mac OSX Snow Leopard.
+* Ruby 1.8.6 on Fedora 13 64bit
+
+# INSTALLING
+1. Ensure Ruby is installed.  
+2. On Fedora 13, install the Ruby Gems package, `[localhost ]$ sudo yum install rubygems`
+2. Install SOAP4R.  `[localhost ]$ sudo gem install soap4r`
+3. Download by clicking on the `Downloads` button above on the right and picking a archive format
+4. Unzip it where you want it to go.   Make sure you unzip into a directory so you don't end up with files everywhere.
+4. Optionally add the new directory you created to your PATH, `PATH=$PATH:~/scripts/JOT/`
+5. Make the `JOT.rb` file executable, `[localhost]$ chmod +x JOT.rb`
+
+# RUNNING
+Run `JOT.rb` and specify arguments as required.  Not rocket science.
+
+    JOT.rb [options]
+        -s, --security                   Retrieve security levels. Slow, dont do it unless necessary
+        -t, --template FILE              template to use
+        -u, --username USERNAME          JIRA username
+        -p, --password PASSWORD          JIRA password
+        -f, --filter FILTER              JIRA filter
+        -h, --help                       Display this screen
+
+E.g. : `[localhost]$ JOT.rb -u joe -p jf84hjf -f "Unresolved JIRAs for 4.8" -t overdue_issues_report.erb`
+
+The error handling for the parameters is pretty terrible right now.  
+
+You need to supply:
+
+1.  `-u` and `-p` for your username and password to authenticate
+2.  `-f` to specify the filter that you are retrieving the list of issues from
+3.  `-t` to specify the template that is to be used to format the output
+
+The only optional parameters right now are `-h` and `-s`.  
+
+* `-h` displays the help and exits.  
+* -s forces it to retrieve the security level information for each issue as well, this is much slower and
+  shouldn't be used unless you need that information.
+
+Currently you can only retrieve data based on a filter that you have "favorited" in JIRA, so you must be 
+authenticated.
+
+An example template, `example.erb`, is included. This template is an example of producing a Docbook XML
+variablelist from some custom fields. Currently this template assumes that the security level information has
+been requested and produces slightly weird output if you haven't specified `-s`.
+
+# CREATING CUSTOM TEMPLATES
+Different templates can be supplied using the `-t` parameter. These templates must be written in Embedded
+Ruby, see <http://en.wikipedia.org/wiki/ERuby>. I hope to be adding more example files in the future.
+
+Note that although the wikipedia page talks about Embedded Ruby in the specific context of generating HTML
+output this is not a limitation. The template doesn't care about anything outside of the `<%` `%>` tags. It
+could be used to produce HTML, XML, CSV or any other text based format you want.
+
+

data/README.rdoc

@@ -0,0 +1,19 @@
+= JOT
+
+Description goes here.
+
+== Contributing to JOT
+ 
+* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
+* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
+* Fork the project
+* Start a feature/bugfix branch
+* Commit and push until you are happy with your contribution
+* Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
+* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
+
+== Copyright
+
+Copyright (c) 2011 Darrin Mison. See LICENSE.txt for
+further details.
+

data/Rakefile

@@ -0,0 +1,62 @@
+# encoding: utf-8
+
+require 'rubygems'
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+require 'rake'
+
+require 'jeweler'
+Jeweler::Tasks.new do |gem|
+  # gem is a Gem::Specification... see http://docs.rubygems.org/read/chapter/20 for more options
+  gem.name = "JOT"
+  gem.homepage = "http://github.com/dmison/JOT"
+  gem.license = "MIT"
+  gem.summary = "CLI for retreiving issues from a JIRA instance and formatting the data."
+  gem.description = "Uses the JIRA SOAP interface to retrieve issues from a JIRA instance for processing with a user specified ERB template."
+  gem.email = "dmison@me.com"
+  gem.authors = ["Darrin Mison"]
+  #files
+  #gem.files = FileList["{bin/*,lib/*,lib/**/*}"].to_a
+  gem.files.include 'bin/*'
+  gem.files.include 'lib/*.rb'
+  gem.files.include 'lib/**/*.rb'
+  gem.files.exclude 'test'
+  gem.require_path = "lib"
+  gem.executables = "JOT"
+
+  # dependencies defined in Gemfile
+end
+Jeweler::RubygemsDotOrgTasks.new
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+end
+
+require 'rcov/rcovtask'
+Rcov::RcovTask.new do |test|
+  test.libs << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+  test.rcov_opts << '--exclude "gems/*"'
+end
+
+task :default => :test
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "JOT #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+1.0.2

data/bin/JOT

@@ -0,0 +1,158 @@
+#!/usr/bin/env ruby -W0
+$LOAD_PATH.unshift File.dirname(__FILE__)
+
+require 'rubygems'
+require 'erb'
+require 'soap/driver'
+require 'optparse'
+
+require 'JIRA-SOAP-STUBS/defaultDriver.rb'
+require 'extension_methods.rb'
+
+#http://docs.atlassian.com/software/jira/docs/api/rpc-jira-plugin/latest/com/atlassian/jira/rpc/soap/JiraSoapService.html
+#wsdl2ruby.rb --wsdl http://issues.jboss.org/rpc/soap/jirasoapservice-v2?wsdl --type=client --module JIRA
+
+def fatalError(message)
+  puts "ERROR COMMUNICATING WITH JIRA:"
+  puts "\t #{message}"      
+  exit
+end
+
+# ======================================== 
+def getFilterID(name, token, driver)
+  favFilters = driver.getFavouriteFilters(token)
+  favFilters.each do |filter|
+    if filter.name == name then 
+      return filter.id 
+    end
+  end
+end
+
+# ======================================== 
+def populateSecurityLevels(issues, soapdriver,loginToken)
+  issues.each do | issue |
+    issue.security_level = soapdriver.getSecurityLevel(loginToken, issue.key).name
+  end
+end
+
+# ======================================== 
+def getIssuesFromFilter( username, password, filter, getSecurityLevels)
+  soapdriver = JIRA::JiraSoapService.new
+
+  begin
+    loginToken = soapdriver.login(username, password)
+  rescue SocketError
+    fatalError("Couldn't open connection.  Check your network.")
+  rescue StandardError
+    fatalError("Login failed.") 
+  end
+
+  filterID = getFilterID(filter, loginToken, soapdriver)
+  issues = soapdriver.getIssuesFromFilter(loginToken, filterID)
+  if (getSecurityLevels) then 
+    populateSecurityLevels(issues, soapdriver, loginToken)
+  end
+  return issues
+end
+
+# ======================================== 
+def getTemplateOutputForIssues(template_file, issues)
+  begin
+    template = ERB.new File.new(template_file).read, nil, "%"
+    template.result(binding)
+    return template.result(binding)
+  rescue => error
+    fatalError("\t#{error.to_s}")
+    exit
+  end
+end
+
+# ======================================== read commandline parameters
+def processCommandLine
+  options = {}
+
+  optparse = OptionParser.new do |opts|
+    opts.banner = "JOT.rb [options]"
+
+    options[:getSecurityLevels] = false
+    opts.on( '-s', '--security', 'Retrieve security levels. Slow, don''t do it unless necessary' ) do
+      options[:getSecurityLevels] = true
+    end
+    
+    options[:template_file] = ""
+    opts.on( '-t FILE', '--template FILE', 'template to use' ) do | file | 
+      options[:template_file] = file
+    end
+    
+    options[:username] = ""
+    opts.on( '-u USERNAME', '--username USERNAME', 'JIRA username' ) do | username |
+      options[:username] = username
+    end
+    
+    options[:password] = ""
+    opts.on( '-p PASSWORD', '--password PASSWORD', 'JIRA password' ) do | password |
+      options[:password] = password
+    end
+      
+    options[:filter] = ""
+    opts.on( '-f FILTER', '--filter FILTER', 'JIRA filter' ) do | filter |
+      options[:filter] = filter
+    end
+
+    options[:query] = ""
+    opts.on( '-q QUERY', '--query QUERY', 'JQL Query [NOT IMPLEMENTED YET]' ) do | query |
+      options[:query] = query
+    end
+    
+    opts.on( '-h', '--help', 'Display this screen' ) do
+      puts opts
+      exit
+    end
+
+    if (ARGV.size == 0) then
+      puts opts
+      exit
+    end
+
+   
+  end
+
+  
+  begin
+    optparse.parse!
+  rescue => error
+    puts "ERROR PARSING COMMANDLINE:"
+    puts "\t"+error.to_s
+    puts
+    puts optparse
+    exit
+  end
+  if (options[:query] != "" and options[:filter] != "") then
+    puts "ERROR PARSING COMMANDLINE:"
+    puts "\tOnly specify a JQL query with -q or a filter with -f, not both."
+    puts
+    puts optparse
+    exit
+  end
+  
+  
+  return options
+end
+
+# ======================================== 
+options = processCommandLine
+
+if (options[:template_file] == "") then
+  issues = getIssuesFromFilter(options[:username], options[:password], options[:filter], options[:getSecurityLevels])
+  
+  issues.each do |issue|
+    puts issue.inspect
+  end
+  
+else
+
+  puts getTemplateOutputForIssues(
+    options[:template_file], 
+    getIssuesFromFilter(options[:username], options[:password], options[:filter], options[:getSecurityLevels]) 
+  )
+end

data/example.erb

@@ -0,0 +1,37 @@
+<?xml version='1.0'?>
+<!DOCTYPE variablelist PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
+
+<% siteURL="https://issues.jboss.org/browse" %>
+<variablelist>
+   <% issues.each do |issue| 
+      release_note_text = issue.getCustomFieldValueForID("customfield_12310211").to_s
+
+      #if the first line of  RNText starts with siteURL
+      finalURL = release_note_text.split("\n")[0].to_s
+      if finalURL.start_with?(siteURL) then 
+         release_note_text = release_note_text.gsub(finalURL+"\n","")
+      else 
+         finalURL = siteURL+"/"+issue.key
+      end
+   %>
+   <!-- <%= siteURL %>/<%= issue.key %> -->
+   <varlistentry>
+      <term><ulink url="<%= finalURL %>" /></term>
+      <listitem>
+         <% if (issue.security_level == "Public") then %>
+         <para>
+         <%= release_note_text.to_x  %>
+         </para>
+         <% else %>
+         <warning>
+            <title>Not Public Yet - <%= issue.security_level %></title>
+            <para>
+            <%= release_note_text.to_x  %>
+            </para>
+         </warning>
+         <% end %>
+      </listitem>
+   </varlistentry>
+<% end %>
+</variablelist>