rally_api 0.4.0

data/README.rdoc

@@ -0,0 +1,104 @@
+RallyAPI (rally_api)
+
+==Description
+
+RallyAPI is a wrapper of Rally's Web Service API Json endpoints
+
+== Installation
+
+gem install rest-client
+gem install json
+gem install rally_api
+
+** Note if you are on Windows - you will need DevKit from http://rubyinstaller.org to properly install the json gem
+**  - that native compiled parsing gives us some speed.
+**  - Follow the instructions here to install DevKit:  https://github.com/oneclick/rubyinstaller/wiki/Development-Kit
+
+== Usage
+
+require 'rally_api'
+
+#Setting custom headers
+headers = RallyAPI::CustomHttpHeader.new()
+headers.name = "My Utility"
+headers.vendor = "MyCompany"
+headers.version = "1.0"
+
+#==================== Making a connection to Rally ====================
+config = {:base_url => "https://rally1.rallydev.com"}
+config[:username]   = "user@company.com"
+config[:password]   = "password"
+config[:workspace]  = "Workspace Name"
+config[:project]    = "Project Name"
+config[:headers]    = headers #from RallyAPI::CustomHttpHeader.new()
+
+@rally = RallyAPI::RallyRestJson.new(config)
+
+#==================== Querying Rally ==========================
+test_query = RallyAPI::RallyQuery.new()
+test_query.type = :defect
+test_query.fetch = "Name"
+test_query.workspace = {"_ref" => "https://rally1.rallydev.com/slm/webservice/1.25/workspace/12345.js" } #optional
+test_query.project = {"_ref" => "https://rally1.rallydev.com/slm/webservice/1.25/project/12345.js" }     #optional
+test_query.page_size = 200       #optional - default is 200
+test_query.limit = 1000          #optional - default is 99999
+test_query.project_scope_up = false
+test_query.project_scope_down = true
+test_query.order = "Name Asc"
+test_query.query_string = "(Severity = \"High\")"
+
+results = @rally.find(test_query)
+
+#tip - set the fetch string of the query to the fields you need -
+#only resort to the read method if you want your code to be slow
+results.each do |defect|
+  puts defect.Name
+  defect.read    #read the whole defect from Rally to get all fields (eg Severity)
+  puts defect.Severity
+end
+
+#==================== Reading an Artifact ====================
+defect = @rally.read(:defect, 12345)      #by ObjectID
+#or
+defect = @rally.read(:defect, "FormattedID|DE42")      #by FormattedID
+#or if you already have an object like from a query
+results = @rally.find(RallyAPI::RallyQuery.new({:type => :defect, :query_string => "(FormattedID = DE42)"}))
+defect = results.first
+defect.read
+
+puts defect["Name"]
+#or - fields can be read by bracket artifact["FieldDisplayName"] or artifact.FieldDisplayName
+puts defect.Name
+
+#An Important note about reading fields and fetching:
+#If you query with a specific fetch string, for example query defect and fetch Name,Severity,Description
+#You will *only* get back those fields defect.Priority will be nil, but may not be null in Rally
+#Use object.read or @rally.read to make sure you read the whole object if you want what is in Rally
+#  This is done for speed - lazy loading (going back to get a value from Rally) can be unneccessarily slow
+#  *Pick you fetch strings wisely* fetch everything you need and don't rely on read if you don't need it the speed is worth it.
+
+#==================== Creating an Artifact ====================
+obj = {}
+obj["Name"] = "Test Defect created #{DateTime.now()}"
+new_de = @rally.create(:defect, obj)
+puts new_de["FormattedID"]
+
+#==================== Updating an Artifact ====================
+fields = {}
+fields["Severity"] = "Critical"
+fields["Description"] = "Description for the issue"
+updated_defect = @rally.update(:defect, 12345, fields)    #by ObjectID
+#or
+updated_defect = @rally.update(:defect, "FormattedID|DE42", fields)   #by FormattedID
+# or
+defect = @rally.read(:defect, 12345)      #by lookup then udpating via the object
+field_updates = {"Description" => "Changed Description"}
+defect.update(field_updates)
+
+
+#== License
+#Copyright (c) 2002-2011 Rally Software Development Corp. All Rights Reserved.
+#Your use of this Software is governed by the terms and conditions
+#of the applicable Subscription Agreement between your company and
+#Rally Software Development Corp.
+

data/Rakefile

@@ -0,0 +1,17 @@
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+task :make_rally_api_gem do
+  system("gem build rally_api.gemspec")
+end
+
+desc "run all api tests"
+RSpec::Core::RakeTask.new('api_tests') do |t|
+  t.pattern = ['test/*_spec.rb']
+end
+
+desc "run api create tests"
+RSpec::Core::RakeTask.new('api_create_tests') do |t|
+  t.pattern = ['test/*create_spec.rb']
+end
+

data/lib/rally_api.rb

@@ -0,0 +1,11 @@
+require "rally_api/version"
+require "rally_api/rally_rest_json"
+
+#Copyright (c) 2002-2012 Rally Software Development Corp. All Rights Reserved.
+#Your use of this Software is governed by the terms and conditions
+#of the applicable Subscription Agreement between your company and
+#Rally Software Development Corp.
+
+module RallyAPI
+  # Your code goes here...
+end

data/lib/rally_api/custom_http_header.rb

@@ -0,0 +1,37 @@
+#Copyright (c) 2002-2012 Rally Software Development Corp. All Rights Reserved.
+#Your use of this Software is governed by the terms and conditions
+#of the applicable Subscription Agreement between your company and
+#Rally Software Development Corp.
+
+require_relative "version"
+
+module RallyAPI
+
+  class CustomHttpHeader
+    attr_accessor :name, :version, :vendor
+    attr_reader :library, :os, :platform
+
+    HTTP_HEADER_FIELDS = [:name, :vendor, :version, :library, :platform, :os]
+    HTTP_HEADER_PREFIX = 'X-RallyIntegration'
+
+    def initialize
+      @os = RUBY_PLATFORM
+      @platform = "Ruby #{RUBY_VERSION}"
+      @library = "RallyRestJson version #{VERSION}"
+      @name = "RallyRestJson"
+    end
+
+    def headers
+      headers = {}
+      HTTP_HEADER_FIELDS.each do |field|
+        value = self.send(field)
+        next if value.nil?
+        header_key = "#{HTTP_HEADER_PREFIX}#{field.to_s.capitalize}"
+        headers[header_key.to_sym] = value
+      end
+      headers
+    end
+  end
+
+end
+

data/lib/rally_api/rally_json_connection.rb

@@ -0,0 +1,203 @@
+require 'rest_client'
+require 'json'
+
+#Copyright (c) 2002-2012 Rally Software Development Corp. All Rights Reserved.
+#Your use of this Software is governed by the terms and conditions
+#of the applicable Subscription Agreement between your company and
+#Rally Software Development Corp.
+module RallyAPI
+
+
+  class RallyJsonConnection
+
+    DEFAULT_PAGE_SIZE = 200
+
+    attr_accessor :rally_headers, :retries, :retry_list
+
+    def initialize(headers, low_debug, proxy_info)
+      @rally_headers = headers
+      @low_debug = low_debug
+      @retries = 0
+      @retry_list = {}
+
+      if (!ENV["http_proxy"].nil?) && (proxy_info.nil?)
+        RestClient.proxy = ENV['http_proxy']
+      end
+
+      if !proxy_info.nil?
+        RestClient.proxy = proxy_info
+      end
+
+    end
+
+    def read_object(url, args)
+      args[:method] = :get
+      result = send_json_request(url, args)
+      puts result if @low_debug
+      rally_type = result.keys[0]
+      result[rally_type]
+    end
+
+    def create_object(url, args, rally_object)
+      args[:method] = :post
+      text_json = rally_object.to_json
+      args[:payload] = text_json
+      puts "payload json: #{text_json}" if @low_debug
+      result = send_json_request(url, args)
+      puts result if @low_debug
+      result["CreateResult"]["Object"]
+    end
+
+    def update_object(url, args, rally_fields)
+      args[:method] = :post
+      text_json = rally_fields.to_json
+      args[:payload] = text_json
+      puts "payload json: #{text_json}" if @low_debug
+      result = send_json_request(url, args)
+      puts result if @low_debug
+      result["OperationResult"]
+    end
+
+    def put_object(url, args, put_params, rally_fields)
+      args[:method] = :put
+      text_json = rally_fields.to_json
+      args[:payload] = text_json
+      result = send_json_request(url, args, put_params)
+      result["OperationResult"]
+    end
+
+    def delete_object(url,args)
+      args[:method] = :delete
+      result = send_json_request(url,args)
+      puts result if @low_debug
+      result["OperationResult"]
+    end
+
+    #---------------------------------------------
+    def get_all_json_results(url, args, query_params, limit = 99999)
+      all_results = []
+      args[:method] = :get
+      params = {}
+      params[:pagesize] = query_params[:pagesize] || DEFAULT_PAGE_SIZE
+      params[:start]    = 1
+      params = params.merge(query_params)
+
+      query_result = send_json_request(url, args, params)
+      all_results.concat(query_result["QueryResult"]["Results"])
+      totals = query_result["QueryResult"]["TotalResultCount"]
+
+      limit < totals ? stop = limit : stop = totals
+      page = params[:pagesize] + 1
+      page_num = 2
+      query_array = []
+      page.step(stop, params[:pagesize]) do |new_page|
+        params[:start] = new_page
+        query_array.push({:page_num => page_num, :url => url, :args => args, :params => params.dup})
+        page_num = page_num + 1
+      end
+
+      all_res = []
+      all_res = run_threads(query_array) if query_array.length > 0
+      #stitch results back together in order
+      all_res.each { |page_res| all_results.concat(page_res[:results]["QueryResult"]["Results"]) }
+
+      query_result["QueryResult"]["Results"] = all_results
+      query_result
+    end
+
+    private
+
+    def run_threads(query_array)
+      num_threads = 4
+      thr_queries = []
+      (0...num_threads).each { |ind| thr_queries[ind] = [] }
+      query_array.each { |query| thr_queries[query[:page_num] % num_threads].push(query) }
+
+      thr_array = []
+      thr_queries.each { |thr_query_array| thr_array.push(run_single_thread(thr_query_array)) }
+
+      all_results = []
+      thr_array.each do |thr|
+        thr.value.each { |result_val| all_results.push(result_val) }
+      end
+      all_results.sort! { |resa, resb| resa[:page_num] <=> resb[:page_num] }
+    end
+
+    def run_single_thread(request_array)
+      Thread.new do
+        thread_results = []
+        request_array.each do |req|
+            page_res = send_json_request(req[:url], req[:args], req[:params])
+            thread_results.push({:page_num => req[:page_num], :results => page_res})
+        end
+        thread_results
+      end
+    end
+
+    #todo support proxy stuff
+    def send_json_request(url, args, url_params = nil)
+      request_args = {}
+      request_args[:url]      = url
+      request_args[:user]     = args[:user]
+      request_args[:password] = args[:password]
+      request_args[:method]   = args[:method]
+      request_args[:timeout]  = 120
+      request_args[:open_timeout] = 120
+
+      r_headers = @rally_headers.headers
+      r_headers[:params] = url_params
+
+      if (args[:method] == :post) || (args[:method] == :put)
+        r_headers[:content_type] = :json
+        r_headers[:accept] = :json
+        request_args[:payload] = args[:payload]
+      end
+
+      request_args[:headers] = r_headers
+
+      begin
+        req = RestClient::Request.new(request_args)
+        puts req.url if @low_debug
+        response = req.execute
+      rescue => ex
+        msg =  "Rally Rest Json: - rescued exception - #{ex.message} on request to #{url} with params #{url_params}"
+        puts msg
+        if !@retry_list.has_key?(req.url)
+          @retry_list[req.url] = 0
+        end
+        if (@retries > 0) && (retry_list[req.url] < @retries)
+          @retry_list[req.url] += 1
+          retry
+        end
+        raise msg
+      end
+      @retry_list.delete(req.url)
+      puts response if @low_debug
+      json_obj = JSON.parse(response.body)   #todo handle null post error
+      errs = check_for_errors(json_obj)
+      raise "\nError on request - #{url} - \n#{errs}" if errs[:errors].length > 0
+      json_obj
+    end
+
+
+    def check_for_errors(result)
+      errors = []
+      warnings = []
+      if !result["OperationResult"].nil?
+        errors    = result["OperationResult"]["Errors"]
+        warnings  = result["OperationResult"]["Warnings"]
+      elsif !result["QueryResult"].nil?
+        errors    = result["QueryResult"]["Errors"]
+        warnings  = result["QueryResult"]["Warnings"]
+      elsif !result["CreateResult"].nil?
+        errors    = result["CreateResult"]["Errors"]
+        warnings  = result["CreateResult"]["Warnings"]
+      end
+
+      {:errors => errors, :warnings => warnings}
+    end
+
+  end
+
+
+end

data/lib/rally_api/rally_object.rb

@@ -0,0 +1,99 @@
+#Copyright (c) 2002-2012 Rally Software Development Corp. All Rights Reserved.
+#Your use of this Software is governed by the terms and conditions
+#of the applicable Subscription Agreement between your company and
+#Rally Software Development Corp.
+module RallyAPI
+
+  class RallyObject
+
+    attr_reader :rally_object
+
+    def initialize(rally_rest, json_hash)
+      @type = json_hash["_type"] || json_hash["_ref"].split("/")[-2]
+      @rally_object = json_hash
+      @rally_rest = rally_rest
+    end
+
+    def update(fields)
+      oid = @rally_object["ObjectID"] || @rally_object["_ref"].split("/")[-1].split(".")[0]
+      @rally_object = @rally_rest.update(@type.downcase.to_sym, oid, fields).rally_object
+    end
+
+    def to_s(*args)
+      @rally_object.to_json
+    end
+
+    def to_json(*args)
+      @rally_object.to_json
+    end
+
+    def [](field_name)
+      get_val(field_name)
+    end
+
+    def read()
+      @rally_object = @rally_rest.reread(@rally_object)
+      self
+    end
+
+    def getref
+      @rally_object["_ref"]
+    end
+
+    def rank_above(relative_rally_object)
+      @rally_rest.rank_above(@rally_object["_ref"],relative_rally_object["_ref"])
+    end
+
+    def rank_below(relative_rally_object)
+      @rally_rest.rank_below(@rally_object["_ref"],relative_rally_object["_ref"])
+    end
+
+    def delete()
+      @rally_rest.delete(@rally_object["_ref"])
+    end
+
+    private
+
+    def method_missing(sym, *args)
+      get_val(sym.to_s)
+    end
+
+    #the magic of lazy loading is gone
+    #def method_missing(sym, *args)
+    #  return_val = get_val(sym.to_s)
+    #
+    #  if return_val.nil?
+    #    @rally_object = @rally_rest.reread(@rally_object)
+    #    return_val = get_val(sym.to_s)
+    #  end
+    #
+    #  return_val
+    #end
+
+    def get_val(field)
+      return_val = @rally_object[field]
+
+      if return_val.class == Hash
+        return RallyObject.new(@rally_rest, return_val)
+      end
+
+      if return_val.class == Array
+        make_object_array(field)
+        return_val = @rally_object[field]
+      end
+
+      return_val
+    end
+
+    def make_object_array(field)
+      object_array = []
+      @rally_object[field].each do |rally_obj|
+        object_array.push(RallyObject.new(@rally_rest, rally_obj))
+      end
+      @rally_object[field] = object_array
+    end
+
+  end
+
+end
+

data/lib/rally_api/rally_query.rb

@@ -0,0 +1,94 @@
+#Copyright (c) 2002-2012 Rally Software Development Corp. All Rights Reserved.
+#Your use of this Software is governed by the terms and conditions
+#of the applicable Subscription Agreement between your company and
+#Rally Software Development Corp.
+module RallyAPI
+    # query is like:
+    # query_hash = {}
+    # query_hash[:type] = Defect, Story, etc
+    # query_hash[:query_string] = "(State = \"Closed\")"
+    # query_hash[:fetch] = "Name,State,etc"
+    # query_hash[:workspace] = workspace json object or ref  #defaults to workspace passed in RallyRestJson.new if nil
+    # query_hash[:project] = project json object or ref      #defaults to project passed in RallyRestJson.new if nil
+    # query_hash[:project_scope_up] = true/false
+    # query_hash[:project_scope_down] = true/false
+    # query_hash[:order] = "ObjectID asc"
+    # query_hash[:page_size]
+    # query_hash[:stopafter]
+
+  class RallyQuery
+    attr_accessor :type, :query_string, :fetch, :workspace, :project, :project_scope_up, :project_scope_down
+    attr_accessor :order, :page_size, :limit
+
+    def initialize(query_hash = nil)
+      parse_query_hash(query_hash) if !query_hash.nil?
+      @page_size          = 200 if @page_size.nil?
+      @limit              = 99999 if @limit.nil?
+      @project_scope_up   = false if @project_scope_up.nil?
+      @project_scope_down = false if @project_scope_down.nil?
+      self
+    end
+
+    def make_query_params
+      query_params = {}
+      query_params[:query]            = @query_string
+      query_params[:fetch]            = @fetch
+      query_params[:workspace]        = @workspace["_ref"] if !@workspace.nil?
+      query_params[:project]          = @project["_ref"] if !@project.nil?
+      query_params[:projectScopeUp]   = @project_scope_up
+      query_params[:projectScopeDown] = @project_scope_down
+      query_params[:order]            = @order
+      query_params[:pagesize]         = @page_size
+
+      query_params
+    end
+
+    def validate(allowed_objects)
+      errors = []
+
+      if @type.nil?
+        errors.push("Object type for query cannot be nil")
+      end
+
+      if @limit < 0
+        errors.push("Stop after - #{@stop_after} - must be a number")
+      end
+
+      if @page_size < 0
+        errors.push("Page size - #{@page_size} - must be a number")
+      end
+
+      if !@workspace.nil?
+        errors.push("Workspace - #{@workspace} - must have a ref") if @workspace["_ref"].nil?
+      end
+
+      if !@project.nil?
+        errors.push("Project - #{@project} - must have a ref") if @project["_ref"].nil?
+      end
+
+      if (allowed_objects[@type].nil?)
+        errors.push( "Object Type #{@type} is not query-able: inspect RallyRestJson.rally_objects for allowed types" )
+      end
+
+      errors
+    end
+
+    private
+
+    def parse_query_hash(query_hash)
+      @type               = query_hash[:type]
+      @query_string       = query_hash[:query_string]
+      @fetch              = query_hash[:fetch]
+      @project_scope_down = query_hash[:project_scope_down]
+      @project_scope_up   = query_hash[:project_scope_up]
+      @order              = query_hash[:order]
+      @page_size          = query_hash[:page_size]
+      @stop_after         = query_hash[:limit]
+      @workspace      = query_hash[:workspace]
+      @project        = query_hash[:project]
+    end
+
+  end
+
+
+end

data/lib/rally_api/rally_query_result.rb

@@ -0,0 +1,36 @@
+#Copyright (c) 2002-2012 Rally Software Development Corp. All Rights Reserved.
+#Your use of this Software is governed by the terms and conditions
+#of the applicable Subscription Agreement between your company and
+#Rally Software Development Corp.
+module RallyAPI
+  class RallyQueryResult
+    include Enumerable
+
+    attr_accessor :results, :total_result_count
+
+    def initialize(rally_rest, json_results)
+      @results            = json_results["QueryResult"]["Results"]
+      @total_result_count = json_results["QueryResult"]["TotalResultCount"]
+      @rally_rest         = rally_rest
+    end
+
+    def each
+      @results.each do |result|
+        yield RallyObject.new(@rally_rest, result)
+      end
+    end
+
+    def [](index)
+      RallyObject.new(@rally_rest, @results[index])
+    end
+
+    def total_results
+      @total_result_count
+    end
+
+    def length
+      @results.length
+    end
+
+  end
+end

data/lib/rally_api/rally_rest_json.rb

@@ -0,0 +1,300 @@
+require_relative "custom_http_header"
+require_relative "rally_json_connection"
+require_relative "rally_object"
+require_relative "rally_query"
+require_relative "rally_query_result"
+
+#Copyright (c) 2002-2012 Rally Software Development Corp. All Rights Reserved.
+#Your use of this Software is governed by the terms and conditions
+#of the applicable Subscription Agreement between your company and
+#Rally Software Development Corp.
+module RallyAPI
+
+  #this contstant is here - a tradeoff of speed vs completeness- right now speed wins because it is so
+  #expensive to query typedef and read all attributes for "OBJECT" or "COLLECTION" types
+  RALLY_REF_FIELDS = { "Subscription" => :subscription, "Workspace" => :workspace, "Project" => :project,
+                       "Iteration" => :iteration, "Release" => :release, "WorkProduct" => :artifact,
+                       "Requirement" => :hierarchicalrequirement, "Owner" => :user, "Tester" => :user,
+                       "RevisionHistory" => :revisionhistory, "Revision" => :revision, "Revisions" => :revision,
+                       "Blocker" => :artifact, "SubmittedBy" => :user, "TestCaseResult" => :testcaseresult,
+                       "TestSet" => :testset, "Parent" => :hierarchicalrequirement, "TestFolder"=> :testfolder }
+
+
+
+  #Main Class to create from when using the tool
+  class RallyRestJson
+    DEFAULT_WSAPI_VERSION = "1.25"
+
+    attr_accessor :rally_url, :rally_user, :rally_password, :rally_workspace_name, :rally_project_name, :wsapi_version
+    attr_accessor :rally_headers, :rally_default_workspace, :rally_default_project, :low_debug, :proxy_info, :retries
+
+    attr_reader   :rally_objects
+
+    def initialize(args)
+      @rally_url            = args[:base_url] || "https://rally1.rallydev.com/slm"
+      @rally_user           = args[:username]
+      @rally_password       = args[:password]
+      @rally_workspace_name = args[:workspace]
+      @rally_project_name   = args[:project]
+      @wsapi_version        = args[:version]  || DEFAULT_WSAPI_VERSION
+      @rally_headers        = args[:headers]  || CustomHttpHeader.new
+      @proxy_info           = args[:proxy]
+      @retries              = args[:retries] || 0
+
+      @low_debug = args[:debug] || false
+
+      @rally_connection = RallyJsonConnection.new(@rally_headers, @low_debug, @proxy_info)
+      if @retries > 0
+        @rally_connection.retries = @retries
+      end
+
+      @rally_objects = { :typedefinition => "TypeDefinition" }
+      cache_rally_objects()
+
+      if !@rally_workspace_name.nil?
+        @rally_default_workspace = find_workspace(@rally_workspace_name)
+        raise "unable to find default workspace #{@rally_workspace_name}" if @rally_default_workspace.nil?
+      end
+
+      if !@rally_project_name.nil?
+        @rally_default_project = find_project(@rally_default_workspace, @rally_project_name)
+        raise "unable to find default project #{@rally_project_name}" if @rally_default_project.nil?
+      end
+
+      self
+    end
+
+    def find_workspace(workspace_name)
+      sub = self.user.Subscription.read()
+      workspace = nil
+      sub.Workspaces.each do |ws|
+        ws.read
+        if (ws.Name == workspace_name) && (ws.State == "Open")
+          workspace = ws
+          break  #doing a break for performance some customers have 100+ workspaces - no need to do the others
+        end
+      end
+      workspace
+    end
+
+    def find_project(workspace_object, project_name)
+      if workspace_object.nil?
+        raise "A workspace must be provided to find a project"
+      end
+
+      query = RallyQuery.new()
+      query.type          = :project
+      query.query_string  = "((Name = \"#{project_name}\") AND (State = \"Open\"))"
+      query.limit         = 20
+      query.fetch         = true
+      query.workspace     = workspace_object
+
+      results = find(query)
+      return results.first if results.length > 0
+      nil
+    end
+
+    def user
+      args = {:user => @rally_user, :password => @rally_password}
+      json_response = @rally_connection.read_object(make_get_url(@rally_objects[:user]), args)
+      RallyObject.new(self, json_response)
+    end
+
+
+    def create(type, fields)
+      rally_type = check_type(type)
+
+      if (fields["Workspace"].nil? && fields["Project"].nil?)
+        fields["Workspace"] = @rally_default_workspace._ref
+        fields["Project"] = @rally_default_project._ref
+      end
+
+      args = {:user => @rally_user, :password => @rally_password }
+      object2create = { rally_type => make_ref_fields(fields) }
+      json_response = @rally_connection.create_object(make_create_url(rally_type), args, object2create)
+      RallyObject.new(self, json_response).read()
+    end
+
+
+    def read(type, obj_id)
+      rally_type = check_type(type)
+      ref = check_id(rally_type, obj_id)
+      args = {:user => @rally_user, :password => @rally_password}
+      json_response = @rally_connection.read_object(ref, args)
+      RallyObject.new(self, json_response)
+    end
+
+    def delete(ref_to_delete)
+      args = {:user => @rally_user, :password => @rally_password}
+      @rally_connection.delete_object(ref_to_delete, args)
+    end
+
+    def reread(json_object)
+      args = {:user => @rally_user, :password => @rally_password}
+      @rally_connection.read_object(json_object["_ref"], args)
+    end
+
+
+    def update(type, obj_id, fields)
+      rally_type = check_type(type)
+      ref = check_id(rally_type, obj_id)
+      json_update = { rally_type => make_ref_fields(fields) }
+      args = {:user => @rally_user, :password => @rally_password}
+      @rally_connection.update_object(ref, args, json_update)
+      RallyObject.new(self, reread({"_ref" => ref}))
+    end
+
+    #query_hash is a has like:
+    # query_hash = {}
+    # query_hash[:type] = Defect, Story, etc
+    # query_hash[:query_string] = "(State = \"Closed\")"
+    # query_hash[:fetch] = "Name,State,etc"
+    # query_hash[:workspace] = workspace json object or ref  #defaults to workspace passed in RallyRestJson.new if nil
+    # query_hash[:project] = project json object or ref      #defaults to project passed in RallyRestJson.new if nil
+    # query_hash[:project_scope_up] = true/false
+    # query_hash[:project_scope_down] = true/false
+    # query_hash[:order] = "ObjectID asc"
+    # query_hash[:pagesize]
+    # query_hash[:stopafter]
+    #todo default workspace and project if not set?
+    def find(query_obj)
+      errs = query_obj.validate(@rally_objects)
+      if errs.length > 0
+        raise "Errors making Rally Query: #{errs.to_s}"
+      end
+
+      query_url = make_query_url(@rally_url, @wsapi_version, check_type(query_obj.type))
+      query_params = query_obj.make_query_params
+      args =  {:user => @rally_user, :password => @rally_password}
+      json_response = @rally_connection.get_all_json_results(query_url, args, query_params, query_obj.limit)
+      RallyQueryResult.new(self, json_response)
+    end
+
+    #rankAbove=%2Fhierarchicalrequirement%2F4624552599
+    #{"hierarchicalrequirement":{"_ref":"https://rally1.rallydev.com/slm/webservice/1.27/hierarchicalrequirement/4616818613.js"}}
+    def rank_above(ref_to_rank, relative_ref)
+      ref = ref_to_rank
+      params = {}
+      params[:rankAbove] = short_ref(relative_ref)
+      params[:fetch] = "true"
+      json_update = { get_type_from_ref(ref_to_rank) => {"_ref" => ref_to_rank} }
+      args = {:user => @rally_user, :password => @rally_password}
+      update = @rally_connection.put_object(ref, args, params, json_update)
+      RallyObject.new(self, update["Object"])
+    end
+
+    #ref to object.js? rankBelow=%2Fhierarchicalrequirement%2F4624552599
+    def rank_below(ref_to_rank, relative_ref)
+      ref = ref_to_rank
+      params = {}
+      params[:rankBelow] = short_ref(relative_ref)
+      params[:fetch] = "true"
+      json_update = { get_type_from_ref(ref_to_rank) => {"_ref" => ref_to_rank} }
+      args = {:user => @rally_user, :password => @rally_password}
+      update = @rally_connection.put_object(ref, args, params, json_update)
+      RallyObject.new(self, update["Object"])
+    end
+
+    private
+
+    def make_get_url(type)
+      "#{@rally_url}/webservice/#{@wsapi_version}/#{type}.js"
+    end
+
+    def make_read_url(type,oid)
+      "#{@rally_url}/webservice/#{@wsapi_version}/#{type}/#{oid}.js"
+    end
+
+    def make_create_url(type)
+      "#{@rally_url}/webservice/#{@wsapi_version}/#{type}/create.js"
+    end
+
+    def make_query_url(rally_url, wsapi_version, type)
+      "#{rally_url}/webservice/#{wsapi_version}/#{type}.js"
+    end
+
+    def short_ref(long_ref)
+      ref_pieces = long_ref.split("/")
+      "/#{ref_pieces[-2]}/#{ref_pieces[-1].split(".js")[0]}"
+    end
+
+    def check_type(type_name)
+      if @rally_objects[type_name].nil?
+        raise "The object type #{type_name} is not valid for the wsapi"
+      end
+      @rally_objects[type_name]
+    end
+
+    #ref should be like https://rally1.rallydev.com/slm/webservice/1.25/defect/12345.js
+    def has_ref?(json_object)
+      if json_object["_ref"].nil?
+        return false
+      end
+      return true if json_object["_ref"] =~ /^https:\/\/\S*(\/slm\/webservice)\S*.js$/
+      false
+    end
+
+    #expecting idstring to have "FormattedID|DE45" or the objectID
+    def check_id(type, idstring)
+      if idstring.class == Fixnum
+        return make_read_url(type, idstring)
+      end
+
+      if (idstring.class == String) && (idstring.index("FormattedID") == 0)
+        return ref_by_formatted_id(type, idstring.split("|")[1])
+      end
+      make_read_url(type, idstring)
+    end
+
+    def ref_by_formatted_id(type, fid)
+      query = RallyQuery.new()
+      query.type          = type.downcase.to_sym
+      query.query_string  = "(FormattedID = #{fid})"
+      query.limit         = 20
+      query.fetch         = "FormattedID"
+      query.workspace     = @rally_default_workspace
+
+      results = find(query)
+      return results.first["_ref"] if results.length > 0
+      nil
+    end
+
+    #eg https://rally1.rallydev.com/slm/webservice/1.25/defect/12345.js
+    def get_type_from_ref(ref)
+      ref.split("/")[-2]
+    end
+
+    def make_ref_fields(fields)
+      fields.each do |key,val|
+        if (val.class == RallyObject)
+          fields[key] = val.getref
+        end
+      end
+      fields
+    end
+
+
+    def cache_rally_objects()
+      type_defs_query = RallyQuery.new()
+      type_defs_query.type = :typedefinition
+      type_defs_query.fetch = "Name"
+
+      type_defs = find(type_defs_query)
+      type_defs.each do |td|
+        type_sym = td.Name.downcase.gsub(" ", "").to_sym
+        @rally_objects[type_sym] = td.Name.gsub(" ","")
+      end
+
+      #some convenience keys to help people - someday we'll fix the api and make HR called story
+      @rally_objects[:artifact]               = "Artifact"
+      @rally_objects[:persistableobject]      = "PersistableObject"
+      @rally_objects[:useriterationcapacity]  = "UserIterationCapacity"
+      @rally_objects[:userpermission]         = "UserPermission"
+      @rally_objects[:story]                  = "HierarchicalRequirement"
+      @rally_objects[:userstory]              = "HierarchicalRequirement"
+
+    end
+
+  end
+
+end

data/lib/rally_api/time_machine_query.rb

@@ -0,0 +1,89 @@
+#Copyright (c) 2002-2012 Rally Software Development Corp. All Rights Reserved.
+#Your use of this Software is governed by the terms and conditions
+#of the applicable Subscription Agreement between your company and
+#Rally Software Development Corp.
+module RallyAPI
+    # query is like:
+    # query_hash = {}
+    # query_hash[:type] = Defect, Story, etc
+    # query_hash[:query_string] = "(State = \"Closed\")"
+    # query_hash[:fetch] = "Name,State,etc"
+    # query_hash[:workspace] = workspace json object or ref  #defaults to workspace passed in RallyRestJson.new if nil
+    # query_hash[:project] = project json object or ref      #defaults to project passed in RallyRestJson.new if nil
+    # query_hash[:project_scope_up] = true/false
+    # query_hash[:project_scope_down] = true/false
+    # query_hash[:order] = "ObjectID asc"
+    # query_hash[:page_size]
+    # query_hash[:stopafter]
+
+  class TimeMachineQuery
+    attr_accessor :workspace
+
+    def initialize(query_hash = nil)
+      parse_query_hash(query_hash) if !query_hash.nil?
+      self
+    end
+
+    def make_query_params
+      query_params = {}
+      #query_params[:query]            = @query_string
+      #query_params[:fetch]            = @fetch
+      query_params[:workspace]        = @workspace["_ref"] if !@workspace.nil?
+      #query_params[:project]          = @project["_ref"] if !@project.nil?
+      #query_params[:projectScopeUp]   = @project_scope_up
+      #query_params[:projectScopeDown] = @project_scope_down
+      #query_params[:order]            = @order
+      #query_params[:pagesize]         = @page_size
+
+      query_params
+    end
+
+    def validate(allowed_objects)
+      errors = []
+
+      if @type.nil?
+        errors.push("Object type for query cannot be nil")
+      end
+
+      if @limit < 0
+        errors.push("Stop after - #{@stop_after} - must be a number")
+      end
+
+      if @page_size < 0
+        errors.push("Page size - #{@page_size} - must be a number")
+      end
+
+      if !@workspace.nil?
+        errors.push("Workspace - #{@workspace} - must have a ref") if @workspace["_ref"].nil?
+      end
+
+      if !@project.nil?
+        errors.push("Project - #{@project} - must have a ref") if @project["_ref"].nil?
+      end
+
+      if (allowed_objects[@type].nil?)
+        errors.push( "Object Type #{@type} is not query-able: inspect RallyRestJson.rally_objects for allowed types" )
+      end
+
+      errors
+    end
+
+    private
+
+    def parse_query_hash(query_hash)
+      #@type               = query_hash[:type]
+      #@query_string       = query_hash[:query_string]
+      #@fetch              = query_hash[:fetch]
+      #@project_scope_down = query_hash[:project_scope_down]
+      #@project_scope_up   = query_hash[:project_scope_up]
+      #@order              = query_hash[:order]
+      #@page_size          = query_hash[:page_size]
+      #@stop_after         = query_hash[:limit]
+      @workspace      = query_hash[:workspace]
+      #@project        = query_hash[:project]
+    end
+
+  end
+
+
+end

data/lib/rally_api/version.rb

@@ -0,0 +1,7 @@
+#Copyright (c) 2002-2012 Rally Software Development Corp. All Rights Reserved.
+#Your use of this Software is governed by the terms and conditions
+#of the applicable Subscription Agreement between your company and
+#Rally Software Development Corp.
+module RallyAPI
+  VERSION = "0.4.0"
+end

metadata

@@ -0,0 +1,67 @@
+--- !ruby/object:Gem::Specification
+name: rally_api
+version: !ruby/object:Gem::Version
+  version: 0.4.0
+  prerelease: 
+platform: ruby
+authors:
+- Dave Smith
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-02-07 00:00:00.000000000Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rest-client
+  requirement: &70332191860000 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 1.6.7
+  type: :runtime
+  prerelease: false
+  version_requirements: *70332191860000
+description: API wrapper for Rally's JSON REST web services api
+email:
+- dsmith@rallydev.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.rdoc
+- Rakefile
+- lib/rally_api/custom_http_header.rb
+- lib/rally_api/rally_json_connection.rb
+- lib/rally_api/rally_object.rb
+- lib/rally_api/rally_query.rb
+- lib/rally_api/rally_query_result.rb
+- lib/rally_api/rally_rest_json.rb
+- lib/rally_api/time_machine_query.rb
+- lib/rally_api/version.rb
+- lib/rally_api.rb
+homepage: http://developer.rallydev.com/help
+licenses: []
+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: rally_api
+rubygems_version: 1.8.6
+signing_key: 
+specification_version: 3
+summary: A wrapper for the Rally Web Services API using json
+test_files: []