jira-remotelinker 0.1.1

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/Gemfile

@@ -0,0 +1,7 @@
+source 'https://rubygems.org'
+gemspec
+
+# Local additions and development tools go here.
+if File.exists? "#{__FILE__}.local"
+  eval(File.read("#{__FILE__}.local"), binding)
+end

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Charlie Sharpsteen
+
+MIT License
+
+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,74 @@
+# jira-remotelinker
+
+A small command line tool for creating bidirectional remote links between JIRA instances through REST API calls.
+
+## Usage
+
+To use this tool, you will need to first connect your JIRA instances through [Application Links](https://confluence.atlassian.com/display/JIRA/Linking+to+Another+Application).
+Then, create a YAML file describing the JIRA instances along with the links that connect them:
+
+```yaml
+public:
+  base_url: 'https://jira6-public.example.com'
+  name: 'Name of Application Link for Private instance'
+  uuid: 'UUID of Application Link for Private instance'
+  username: 'some user with create link permissions'
+  password: 'password for user'
+private:
+  base_url: 'https://jira6-private.example.com'
+  name: 'Name of Application Link for Public instance'
+  uuid: 'UUID of Application Link for Public instance'
+  username: 'some user with create link permissions'
+  password: 'password for user'
+```
+
+Discovering the UUID associated with an application link is a bit tricky as this value does not appear to be publicly exposed.
+However, the UUID is required for the creation of fully functioning cross-application links.
+One way to extract the `uuid` associated with an application link is through the following database query (tested on JIRA 6.1.x backed by PostgreSQL):
+
+```sql
+/* Retrieve Application Link names and UUIDs From JIRA
+ * Based on a query described in the Atlassian troubleshooting docs:
+ *
+ *   https://confluence.atlassian.com/display/JIRAKB/How+to+remove+Application+link+directly+through+database
+ *
+ */
+SELECT
+  propertystring.propertyvalue AS "name",
+  SUBSTR(propertyentry.property_key,16,36) AS "uuid"
+FROM
+  propertyentry, propertystring
+WHERE
+  propertyentry.id = propertystring.id AND
+  propertyentry.property_key like 'applinks.admin%name';
+
+```
+
+The second piece of required input is a CSV file containing the issue link data.
+The required pieces of data are:
+
+  - **source_instance:** The name of a JIRA instance defined in the YAML configuration file.
+  - **source_id:** The global numeric id of the source ticket.
+  - **source_key:** The project-specific id of the source ticket (i.e. "PUB-2").
+  - **source_relation:** The relationship between the source ticket and the target ticket (i.e. "blocks").
+  - **target_instance:** The name of a JIRA instance defined in the YAML configuration file.
+  - **target_id:** The global numeric id of the target ticket.
+  - **target_key:** The project-specific id of the target ticket (i.e. "PRIV-20").
+  - **target_relation:** The relationship between the target ticket and the source ticket (i.e. "blocked by").
+
+These fields are laid in a CSV file in the following order:
+
+source_instance | source_id | source_key | source_relation | target_instance | target_id | target_key | target_relation
+--- | --- | --- | --- | --- | --- | --- | ---
+public | 10020 | PUB-2 | blocks | private | 11234 | PRIV-20 | blocked by
+public | 10042 | PUB-7 | duplicated by | private | 11555 | PRIV-42 | duplicates
+
+
+Once the YAML and CSV files have been created, the tool can be invoked:
+
+    jira-remotelinker jira_instances.yaml link_data.csv
+
+---
+<p align="center">
+  <img src="http://i.imgur.com/iDFAxAM.jpg" />
+</p>

data/bin/jira-remotelinker

@@ -0,0 +1,52 @@
+#!/usr/bin/env ruby
+
+require 'optparse'
+require 'methadone'
+require 'progressbar'
+
+require 'yaml'
+require 'csv'
+
+require 'jira-remotelinker'
+
+class App
+  include Methadone::Main
+  include Methadone::CLILogging
+
+  description 'A small command line tool for creating remote links through the JIRA REST API'
+  version JiraRemotelinker::VERSION
+
+  use_log_level_option
+
+  arg :jira_config, 'A YAML file containing configuration and API access info for the target JIRA instances'
+  arg :link_data, 'A CSV file containing issue link data'
+
+  main do |jira_config, link_data|
+    config = YAML.load_file jira_config
+
+    # Create a REST client for each JIRA instance defined in the config.
+    config.each do |_, instance|
+      instance['client'] = JiraRemotelinker::REST.factory instance['base_url'], instance['username'], instance['password'],
+        instance['name'], instance['uuid']
+    end
+
+    links = CSV.table link_data
+    pbar = ProgressBar.new 'making links', links.length
+
+    links.each do |row|
+      # Create link from source JIRA -> target JIRA
+      config[row[:source_instance]]['client'].post_issue_remotelink row[:source_key], row[:source_relation],
+        config[row[:target_instance]]['client'], row[:target_key], row[:target_id]
+
+      # Create reciprocal link from target JIRA -> source JIRA
+      config[row[:target_instance]]['client'].post_issue_remotelink row[:target_key], row[:target_relation],
+        config[row[:source_instance]]['client'], row[:source_key], row[:source_id]
+
+      pbar.inc
+    end
+
+    pbar.finish
+  end
+
+  go!
+end

data/examples/get_applink_uuid.sql

@@ -0,0 +1,14 @@
+/* Retrieve Application Link names and UUIDs From JIRA
+ * Based on a query retrieved from the Atlassian troubleshooting docs:
+ *
+ *   https://confluence.atlassian.com/display/JIRAKB/How+to+remove+Application+link+directly+through+database
+ *
+ */
+SELECT
+  propertystring.propertyvalue AS "name",
+  SUBSTR(propertyentry.property_key,16,36) AS "uuid"
+FROM
+  propertyentry, propertystring
+WHERE
+  propertyentry.id = propertystring.id AND
+  propertyentry.property_key like 'applinks.admin%name';

data/examples/get_links_to_migrate.sql

@@ -0,0 +1,91 @@
+/* Huge, hairy SELECT statement that copies link data to CSV */
+COPY (
+WITH
+
+  /* This defines the group of projects which are migrating to a new JIRA
+   * instance
+   */
+  migrated_projects AS (
+    VALUES
+      ('FACT'),
+      ('PP'),
+      ('HI'),
+      ('OS'),
+      ('MCO'),
+      ('PDB'),
+      ('GTO'),
+      ('RAZOR')
+  ),
+
+  /* JIRA 6.1 replaced the pkey column which held the issue key, "PP-22", with
+   * the issuenum column which just holds the issue number: "22". This view
+   * re-constitutes the issue keys, plus saves the project identifier, "PP", so
+   * that it can be later checked against the list defined above.
+   */
+  munged_issues AS (
+    SELECT
+      jiraissue.id,
+      project.pkey || '-' || jiraissue.issuenum AS "key",
+      project.pkey
+    FROM
+      jiraissue,
+      project
+    WHERE
+      jiraissue.project = project.id
+  ),
+
+  /* This selects all links that originate OR terminate in the group of
+   * migrated projects but do not originate AND terminate in the group of
+   * migrated projects.
+   */
+  munged_links AS (
+    SELECT
+      issuelink.*
+    FROM
+      issuelink
+    JOIN
+      munged_issues AS source_issue
+      ON issuelink.source = source_issue.id
+    JOIN
+      munged_issues AS dest_issue
+      ON issuelink.destination = dest_issue.id
+    WHERE
+      (
+        source_issue.pkey IN (SELECT * FROM migrated_projects) AND
+        dest_issue.pkey NOT IN (SELECT * FROM migrated_projects)
+      ) OR
+      (
+        source_issue.pkey NOT IN (SELECT * FROM migrated_projects) AND
+        dest_issue.pkey IN (SELECT * FROM migrated_projects)
+      )
+  )
+
+/* This selection gathers link data targetted by the munged_links query and
+ * exports it to CSV in the format expected by the jira-remotelinker tool.
+ */
+SELECT
+  CASE
+    WHEN source_issue.pkey IN (SELECT * FROM migrated_projects) THEN 'public'
+    ELSE 'private' END
+  AS "source_instance",
+  source AS "source_id",
+  source_issue.key AS "source_key",
+  outward AS "source_relation",
+  CASE
+    WHEN dest_issue.pkey NOT IN (SELECT * FROM migrated_projects) THEN 'private'
+    ELSE 'public' END
+  AS "target_instance",
+  destination AS "target_id",
+  dest_issue.key AS "target_key",
+  inward AS "target_relation"
+FROM munged_links AS issuelink
+JOIN
+  issuelinktype AS type
+  ON issuelink.linktype = type.id
+JOIN
+  munged_issues AS source_issue
+  ON issuelink.source = source_issue.id
+JOIN
+  munged_issues AS dest_issue
+  ON issuelink.destination = dest_issue.id )
+TO '/tmp/links_to_migrate.csv' WITH CSV HEADER;

data/examples/jira_config.yaml

@@ -0,0 +1,13 @@
+public:
+  base_url: 'https://jira6-public.example.com'
+  # See get_applink_uuid.sql for a method of retrieving the Name and UUID
+  name: 'Name of Application Link for Private instance'
+  uuid: 'UUID of Application Link for Private instance'
+  username: 'some user with create link permissions'
+  password: 'password for user'
+private:
+  base_url: 'https://jira6-private.example.com'
+  name: 'Name of Application Link for Public instance'
+  uuid: 'UUID of Application Link for Public instance'
+  username: 'some user with create link permissions'
+  password: 'password for user'

data/jira-remotelinker.gemspec

@@ -0,0 +1,24 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'jira-remotelinker/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'jira-remotelinker'
+  spec.version       = JiraRemotelinker::VERSION
+  spec.authors       = ['Charlie Sharpsteen']
+  spec.email         = ['source@sharpsteen.net']
+  spec.description   = %q{A small command line tool for creating remote links through the JIRA REST API}
+  spec.summary       = %q{This tool reads in issue link information from CSV and creates remote links using v2 of the JIRA REST API.}
+  spec.homepage      = 'https://github.com/Sharpie/jira-remotelinker'
+  spec.license       = 'MIT'
+
+  spec.files         = `git ls-files`.split($/)
+  spec.require_paths = ['lib']
+  spec.bindir        = 'bin'
+  spec.executables   = ['jira-remotelinker']
+
+  spec.add_runtime_dependency 'methadone', '~> 1.3.0'
+  spec.add_runtime_dependency 'httparty', '~> 0.12.0'
+  spec.add_runtime_dependency 'progressbar'
+end

data/lib/jira-remotelinker.rb

@@ -0,0 +1,5 @@
+module JiraRemotelinker
+end
+
+require 'jira-remotelinker/version'
+require 'jira-remotelinker/rest'

data/lib/jira-remotelinker/rest.rb

@@ -0,0 +1,65 @@
+require 'httparty'
+
+module JiraRemotelinker
+  module REST
+    # An abstract template class that talks to v2 of the JIRA API.
+    # Instantiate concrete subclasses using the module function `factory`.
+    class AbstractV2
+      API_PATH = 'rest/api/2'
+      include HTTParty
+      format :json
+
+      # Sets three instance variables that represent a JIRA Application Link
+      class << self
+        attr_accessor :jira_type, :jira_name, :jira_uuid, :jira_url
+      end
+
+      def self.get_issue(issue_key)
+        get "/issue/#{issue_key}"
+      end
+
+      def self.get_issue_remotelinks(issue_key)
+        get "/issue/#{issue_key}/remotelink"
+      end
+
+      def self.post_issue_remotelink(issue_key, relationship, target_jira, target_key, target_id)
+        link_data = {
+          'globalId' => "appId=#{target_jira.jira_uuid}&issueId=#{target_id}",
+          'application' => {
+            'type' => target_jira.jira_type,
+            'name' => target_jira.jira_name
+          },
+          'relationship' => relationship,
+          'object' => {
+            'url' => "#{target_jira.jira_url}/browse/#{target_key}",
+            'title' => target_key
+          }
+        }
+
+        post "/issue/#{issue_key}/remotelink", {:body => link_data.to_json, :headers => {'Content-Type' => 'application/json'}}
+      end
+
+      def self.delete_issue_remotelink(issue_key, link_id)
+        delete "/issue/#{issue_key}/remotelink/#{link_id}"
+      end
+    end
+
+    module_function
+
+    # Create a concrete class that talks to a particular JIRA instance using the V2 API.
+    def factory(url, username, password, name, uuid, type = 'com.atlassian.jira')
+      Class.new(AbstractV2) do |klass|
+        klass.base_uri(File.join(url, AbstractV2::API_PATH))
+        klass.basic_auth(username, password)
+
+        # These are used during Remote Link creation and allow JIRA instances
+        # to pull issue data from each other and ensure that users are properly
+        # authorized to view such data.
+        klass.jira_name = name
+        klass.jira_uuid = uuid
+        klass.jira_type = type
+        klass.jira_url = url
+      end
+    end
+  end
+end

data/lib/jira-remotelinker/version.rb

@@ -0,0 +1,3 @@
+module JiraRemotelinker
+  VERSION = "0.1.1"
+end

metadata

@@ -0,0 +1,110 @@
+--- !ruby/object:Gem::Specification
+name: jira-remotelinker
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+  prerelease: 
+platform: ruby
+authors:
+- Charlie Sharpsteen
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-10-30 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: methadone
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.3.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.3.0
+- !ruby/object:Gem::Dependency
+  name: httparty
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.12.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.12.0
+- !ruby/object:Gem::Dependency
+  name: progressbar
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: A small command line tool for creating remote links through the JIRA
+  REST API
+email:
+- source@sharpsteen.net
+executables:
+- jira-remotelinker
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- LICENSE
+- README.md
+- bin/jira-remotelinker
+- examples/get_applink_uuid.sql
+- examples/get_links_to_migrate.sql
+- examples/jira_config.yaml
+- jira-remotelinker.gemspec
+- lib/jira-remotelinker.rb
+- lib/jira-remotelinker/rest.rb
+- lib/jira-remotelinker/version.rb
+homepage: https://github.com/Sharpie/jira-remotelinker
+licenses:
+- MIT
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.23
+signing_key: 
+specification_version: 3
+summary: This tool reads in issue link information from CSV and creates remote links
+  using v2 of the JIRA REST API.
+test_files: []
+has_rdoc: