mingle4r 0.3.0

data/History.txt

@@ -0,0 +1,40 @@
+0.3.0
+-----
+
+* Major refactoring. The internal structure is completely changed
+* supports both Mingle 2 and Mingle 3. Mingle 2 support is deprecated and will be removed in the next release.
+* new Mingle 3 api features added - murmurs, comment
+
+0.2.2
+-----
+
+* added add_comment to card class. allows adding comment to a card
+
+0.2.1
+-----
+
+* added option to relationship methods(e.g. - cards, users, attachments) to return cached or 
+updated results
+* property_definitions is a relationship method of project instead of mingle client.
+
+0.2.0
+-----
+
+* added class method apply_filter to Card class. allows an MQL filter
+* added instance method execute_transition to Card class. allows to execute a transition on a card.
+
+0.1.6
+-----
+
+* added instance method at_version to Card class. gets the particular version for the card
+
+0.1.5
+-----
+
+* Rest Api's added - wiki
+
+0.0.1
+-----
+
+* Rest Api's - Card, Project, User, Attachment, Property Definition
+* Mingle Client - supports getting cards, project etc.

data/MIT-LICENSE

@@ -0,0 +1,21 @@
+The MIT License
+
+Copyright (c) 2009 Arusarka Haldar
+
+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

@@ -0,0 +1,227 @@
+== mingle4r
+
+http://github.com/arusarka/mingle4r/tree/master
+
+== DESCRIPTION:
+
+This gem is a wrapper around active resource to access the rest api exposed by mingle
+(http://studios.thoughtworks.com/mingle-agile-project-management).It provides a easy 
+way to communicate with mingle. For the library to work you need to enable basic authentication
+(not enabled by default) in Mingle. See below to enable basic authentication in Mingle.
+
+However if you are planning to connect and work with mingle from the terminal, then there
+is another gem mingle-mingle which you should look at. This library provides a very easy
+api to write code to work with mingle (see the examples below) but thats it.
+
+Enable basic authentication in Mingle
+-------------------------------------
+
+1) Go to Mingle DataDir
+
+2) Open YAML file <Mingle DataDir>/config/auth_config.yml
+
+3) Set 'basic_authentication_enabled' to 'true' (without the quotes) if it is not so
+
+== FEATURES/PROBLEMS:
+
+It gives you access to projects in the mingle instance, cards under the project and also
+attachments for a particular card. 
+
+== SYNOPSIS:
+
+The api now supports both mingle 2 and mingle 3. The gem tries as much as possible to hide
+away the internal details. But some api features are only supported in mingle 3 only (like
+murmurs). For that check the api documentation for the mingle instance(located at 
+<mingle instance host>/help/index)
+
+In all the documentation below you can replace Mingle4r::MingleClient with MingleClient.
+Its an alias for easy use.
+
+A) Getting all the projects for a particular instance
+-----------------------------------------------------
+
+Suppose you want to connect to the mingle instance hosted at http://localhost:8080 where the
+username is 'testuser' and password is 'password'.
+
+m_c = Mingle4r::MingleClient.new('http://localhost:8080', 'testuser', 'password')
+projs = m_c.projects
+
+projs is an array of active resource objects
+
+B) Getting a particular project
+-------------------------------
+
+Before you access a particular project you need to set the project id for the mingle client 
+object. You can do that in two ways. Supposing you are trying to access a project with an
+identifier of 'great_mingle_project'
+
+WARNING : project identifier and project name are different. If you named your project as
+'Great Mingle Project' it's identifier is by default 'great_mingle_project'. To be sure what
+the identifier of a project is you should look at the url in mingle in the particular project
+you are trying to access. It should be something like 'http://localhost:8080/projects/great_mingle_project'
+
+		1) Set at initialize time
+
+		m_c = Mingle4r::MingleClient.new('http://localhost:8080', 'testuser', 'password',
+		'great_mingle_project')
+		m_c.project
+
+		2) Set an attribute later
+
+		m_c = Mingle4r::MingleClient.new('http://localhost:8080', 'testuser', 'password')
+		m_c.proj_id = 'great_mingle_project'
+		m_c.project
+
+C) Getting cards for a particular project
+--------------------------------------
+
+Get a mingle client object initialized as in SECTION B. Then call the cards method.
+
+m_c = Mingle4r::MingleClient.new('http://localhost:8080', 'testuser', 'password')
+m_c.proj_id = 'great_mingle_project'
+m_c.project.cards
+
+cards will be an array of activeresoure objects.
+
+D) Getting custom properties for a card
+---------------------------------------
+
+m_c = Mingle4r::MingleClient.new('http://localhost:8080', 'testuser', 'password')
+m_c.proj_id = 'great_mingle_project'
+card = m_c.project.cards[0]
+card.custom_properties => returns an array of hashes, {property name => property value}
+
+However this gives only custom properties, not all the properties.
+
+E) Getting a particular property
+--------------------------------
+
+gets the value of a property. The property name given should be the same as seen in Mingle.
+
+m_c = Mingle4r::MingleClient.new('http://localhost:8080', 'testuser', 'password')
+m_c.proj_id = 'great_mingle_project'
+card = m_c.project.cards[0]
+card.property_value('Status')
+
+F) Setting a particular property
+--------------------------------
+
+sets the value of the property. The property name given should be the same as in Mingle and
+the value given should be one of the values that Mingle accepts in case of a managed list
+
+m_c = Mingle4r::MingleClient.new('http://localhost:8080', 'testuser', 'password')
+m_c.proj_id = 'great_mingle_project'
+defect_card = m_c.project.cards.first
+defect_card.property_value('Status', 'Closed')
+
+G) Adding comment to a particular card
+--------------------------------------
+
+m_c = Mingle4r::MingleClient.new('http://localhost:8080', 'testuser', 'password')
+m_c.proj_id = 'great_mingle_project'
+defect_card = m_c.project.cards[0]
+defect_card.add_comment('Not able to reproduce')
+
+H) Getting all comments for a card(only in mingle 3.0)
+------------------------------------------------------
+m_c = Mingle4r::MingleClient.new('http://localhost:8080', 'testuser', 'password')
+m_c.proj_id = 'great_mingle_project'
+defect_card = m_c.project.cards.first
+defect_cards.comments
+
+I) Attachments
+--------------
+m_c = Mingle4r::MingleClient.new('http://localhost:8080', 'testuser', 'password')
+m_c.proj_id = 'great_mingle_project'
+defect_card = m_c.project.cards.first
+defect_card.attachments
+
+  1) Downloading a particular attachment
+  --------------------------------------
+  
+  attachment = defect_card.attachments.first
+  attachment.save('page.css')
+  
+  2) Uploading an attachment
+  --------------------------
+  
+  defect_card.upload_attachment('page-screenshot.jpg')
+  
+J) Murmurs(only in Mingle 3.0)
+------------------------------
+
+  1) Get the murmurs for a project
+  --------------------------------
+  
+  m_c = Mingle4r::MingleClient.new('http://localhost:8080', 'testuser', 'password')
+  m_c.proj_id = 'great_mingle_project'
+  project = m_c.project
+  project.murmurs
+  
+  2) Get the murmurs associated with a card
+  -----------------------------------------
+  
+  card = project.cards.first
+  card.murmurs
+  
+  3) post a murmur(hooray!)
+  -------------------------
+  project.post_murmur('my first murmur, I am excited!')
+  
+K) Get all transitions for a card(only in Mingle 3.0)
+-----------------------------------------------------
+
+m_c = Mingle4r::MingleClient.new('http://localhost:8080', 'testuser', 'password')
+m_c.proj_id = 'great_mingle_project'
+defect_card = m_c.project.cards.first
+
+defect_card.transitions
+
+L) Execute a transition on a card
+---------------------------------
+
+m_c = Mingle4r::MingleClient.new('http://localhost:8080', 'testuser', 'password')
+m_c.proj_id = 'great_mingle_project'
+defect_card = m_c.project.cards.first
+
+defect_card.execute_transition(
+ 'name'/'transition' => name of the transition to execute exactly s in Mingle(required in 2,3 but
+not required in 3.0)
+ 'comment' => comment for the transition, required only if the transition requires a comment
+ 'Property Name as in Mingle exactly' => 'Property value to set for the property', required only
+if the transition requires to be set manually.
+)
+
+== REQUIREMENTS:
+
+1) active_resource gem, it would be automatically taken care of
+during gem install.
+
+== INSTALL:
+
+sudo (not on windows) gem install mingle4r
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2009 Arusarka Haldar
+
+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/TODO.txt

@@ -0,0 +1,7 @@
+update documentation
+write tests for mingle4r/mingle_client
+
+refactorings
+------------
+remove calling create_resource_class through send
+remove checking for cache through a variable. check the results container directly

data/lib/mingle4r/api/v1/card/attachment.rb

@@ -0,0 +1,51 @@
+module Mingle4r
+  class API
+    class V1
+      class Card
+        class Attachment
+          module InstanceMethods
+            # downloads the attachment. It an additional file path is given it saves it at the 
+            # given path. The given path should be writable
+            def download(file_name = nil)
+              collection_uri = self.class.site
+              rel_down_url = self.url
+              base_url = "#{collection_uri.scheme}://#{collection_uri.host}:#{collection_uri.port}/"
+              down_uri = URI.join(base_url, rel_down_url)
+              req = Net::HTTP::Get.new(down_uri.path)
+              req.basic_auth self.class.user, self.class.password
+              begin
+                res = Net::HTTP.start(down_uri.host, down_uri.port) { |http| http.request(req) }
+                file_name ||= self.file_name()
+                File.open(file_name, 'w') { |f| f.print(res.body) }
+              rescue Exception => e
+                e.message
+              end
+            end # download
+
+            # alias for file_name
+            def name
+              file_name()
+            end
+
+            # so that active resource tries to find by proper id
+            def id
+              name()
+            end
+
+            # This method had to be overriden. 
+            # normal active resource destroy doesn't work as mingle site for deleting attachments doesn't end with .xml.
+            def destroy
+              connection = self.send(:connection)
+              # deletes the attachment by removing .xml at the end
+              connection.delete(self.send(:element_path).gsub(/\.xml\z/, ''))
+            end
+            alias_method :delete, :destroy
+          end #module InstanceMethods
+
+          extend Mingle4r::CommonClassMethods
+
+        end # class Attachment
+      end # class Card
+    end # class V1
+  end # class API
+end # module Mingle4r

data/lib/mingle4r/api/v1/card.rb

@@ -0,0 +1,173 @@
+module Mingle4r
+  class API
+    class V1
+      class Card
+        extend Mingle4r::CommonClassMethods
+        
+        # overwrite the default find in CommonClassMethods
+        def self.find(*args)
+          scope = args.slice!(0)
+          options = args.slice!(0) || {}
+          @resource_class.find_without_pagination(scope, options)
+        end
+        
+        module ClassMethods
+          def find_without_pagination(*args)
+            scope = args.slice!(0)
+            options = args.slice!(0) || {}
+            options[:params] ||= {}
+            options[:params].merge!({:page => 'all'})
+
+            # call ActiveResource::Base::find with proper options
+            find(scope, options)
+          end
+
+          # applies an mql filter on card types. Look at https://mingle05.thoughtworks.com/help/mql_reference.html
+          # for reference
+          def apply_filter(filter_string)
+            find_without_pagination(:all, :params => {'filters[mql]'.to_sym => filter_string})
+          end
+        end
+
+        module InstanceMethods
+          def attachments(refresh = false)
+            return @attachments if(!refresh && @attachments_cached)
+            attachment_site = File.join(self.class.site.to_s, "cards/#{self.number()}").to_s
+            Attachment.site = attachment_site
+            Attachment.user = self.class.user
+            Attachment.password = self.class.password
+            attachment_class = Attachment.send(:create_resource_class)
+            @attachments = attachment_class.find(:all)
+            @attachments_cached = true
+            @attachments
+          end
+
+          def upload_attachment(file_path)
+            attachment_uri   = URI.parse(File.join(self.class.site.to_s, "cards/#{self.number()}/attachments.xml"))
+            http             = Net::HTTP.new(attachment_uri.host, attachment_uri.port)
+            http.use_ssl     = attachment_uri.is_a?(URI::HTTPS)
+            http.verify_mode = OpenSSL::SSL::VERIFY_NONE if http.use_ssl
+            basic_encode     = 'Basic ' + ["#{self.class.user}:#{self.class.password}"].pack('m').delete("\r\n")
+
+            post_headers = {
+              'Authorization' => basic_encode,
+              'Content-Type'  => 'multipart/form-data; boundary=----------XnJLe9ZIbbGUYtzPQJ16u1'
+            }
+
+            file_content = IO.read(file_path)
+
+            post_body = <<EOS
+------------XnJLe9ZIbbGUYtzPQJ16u1\r
+Content-Disposition: form-data; name="file"; filename="#{File.basename(file_path)}"\r
+Content-Type: application/octet-stream\r
+Content-Length: #{file_content.size}\r
+\r
+#{file_content}\r
+------------XnJLe9ZIbbGUYtzPQJ16u1--\r
+EOS
+        
+            http.post(attachment_uri.path, post_body, post_headers)
+          end
+      
+          # returns back the version of the card given. If an invalid version is given, the latest
+          # version is returned, takes a number or :next or :before
+          def at_version(version_no)
+            version_2_find = 0
+            case version_no
+            when :before
+              version_2_find = self.version.to_i - 1
+            when :next
+              version_2_find = self.version.to_i + 1
+            else
+              version_2_find = version_no.to_i
+            end
+            self.class.find(self.number, :params => {:version => version_2_find})
+          end
+
+          # adds a comment to a card.
+          def add_comment(comment)
+            comment_uri = URI.parse(File.join(self.class.site.to_s, "cards/add_comment?card_id=#{self.id}"))
+        
+            http             = Net::HTTP.new(comment_uri.host, comment_uri.port)
+            http.use_ssl     = comment_uri.is_a?(URI::HTTPS)
+            http.verify_mode = OpenSSL::SSL::VERIFY_NONE if http.use_ssl
+        
+            basic_encode = 'Basic ' + ["#{self.class.user}:#{self.class.password}"].pack('m').delete("\r\n")
+        
+            post_headers = {
+              'Authorization' => basic_encode,
+              'Content-Type'  => 'application/x-www-form-urlencoded; charset=UTF-8'
+            }
+        
+            post_body = "comment=#{comment}&card_id=#{self.id}"
+        
+            http.post(comment_uri.path, post_body, post_headers)
+          end
+      
+          # Executes the given transition on the card.
+          # Example :
+          # defect_card.execute_transition(:name => 'Close Defect', :Owner => nil, :Status => 'Closed', :transition_comment => comment)
+          # transition_comment is mandatory if the transition is set that way.
+          # after transition 'Owner' would have value 'Not Set' and 'Status' would be 'Closed' for defect card
+          def execute_transition(args = {})
+            V1::TransitionExecution.site     = self.class.site.to_s
+            V1::TransitionExecution.user     = self.class.user
+            V1::TransitionExecution.password = self.class.password
+            
+            args.symbolize_keys!
+            trans_hash = create_transition_exec_hash(args)
+            V1::TransitionExecution.new(trans_hash).execute
+          end
+      
+          # gets the value of a property. The property name given should be the same name as
+          # the mingle property name
+          def property_value(name, val = nil)
+            set_property_definitions_attributes
+            column_name = PropertyDefinition.column_name_for(name.to_s)
+            val ? attributes[column_name] = val : attributes[column_name]
+          end
+
+          def custom_properties
+            set_property_definitions_attributes
+            custom_props = []
+            card_props = attributes.keys
+            PropertyDefinition.find(:all).each do |prop|
+              if(card_props.include?(prop.column_name))
+                custom_prop = {prop.name => attributes[prop.column_name]}
+                custom_props.push(custom_prop)
+              end
+            end
+            custom_props
+          end
+      
+          private
+          def boundary
+            '----------XnJLe9ZIbbGUYtzPQJ16u1'
+          end
+          
+          def create_transition_exec_hash(args)
+            transition_hash = {}
+            transition_hash['card'] = (args.delete(:card) || self.number).to_i
+            transition_hash['transition'] = (args.delete(:name) || args.delete(:transition))
+            
+            comment = args.delete(:comment)
+            transition_hash['comment'] = comment if comment
+            properties = []
+            args.each do |name, value|
+              property = {'name' => name.to_s, 'value' => value}
+              properties.push(property)
+            end
+            transition_hash['properties'] = properties unless properties.empty?
+            transition_hash
+          end
+          
+          def set_property_definitions_attributes
+            PropertyDefinition.site = self.class.site.to_s
+            PropertyDefinition.user = self.class.user
+            PropertyDefinition.password = self.class.password
+          end
+        end
+      end
+    end
+  end
+end

data/lib/mingle4r/api/v1/project.rb

@@ -0,0 +1,71 @@
+# require File.dirname(__FILE__) + '/../common/project'
+module Mingle4r
+  class API
+    class V1
+      class Project
+        
+        extend Mingle4r::CommonClassMethods
+                
+        module InstanceMethods
+          # returns the cards for the project. To hit the resource server without returning
+          # cached results pass true as an argument.
+          def cards(refresh = false)
+            return @cards if(!refresh && @cards_cached)
+            cards_site = File.join(self.class.site.to_s, "projects/#{self.identifier()}")
+            # card_class = API.new(self.class.site).card_class
+            Card.site = cards_site
+            Card.user = self.class.user
+            Card.password = self.class.password
+            # @cards = Card.send(:create_resource_class).find_without_pagination(:all)
+            @cards = Card.find_without_pagination(:all)
+            @cards_cached = true
+            @cards
+          end
+
+          # returns the users for the project. To hit the resource server without returning
+          # cached results pass true as an argument.
+          def users(refresh = false)
+            return @users if(!refresh && @users_cached)
+            users_site = File.join(self.class.site.to_s, "projects/#{self.identifier()}")
+            User.site = users_site
+            User.user = self.class.user
+            User.password = self.class.password
+            User.element_name = nil # reset
+            user_class = User.send(:create_resource_class)
+            @users = user_class.find(:all)
+            @users_cached = true
+            @users
+          end
+
+          # returns the wikis for the project. To hit the resource server without returning
+          # cached results pass true as an argument.
+          def wikis(refresh = false)
+            return @wikis if(!refresh && @wikis_cached)
+            wiki_site = File.join(self.class.site.to_s, "projects/#{self.identifier()}")
+            Wiki.site = wiki_site
+            Wiki.user = self.class.user
+            Wiki.password = self.class.password
+            wiki_class = Wiki.send(:create_resource_class)
+            @wikis = wiki_class.find(:all)
+            @wikis_cached = true
+            @wikis
+          end
+
+          # returns the property definitions for the project. To hit the resource server
+          # pass true as an argument
+          def property_definitions(refresh = false)
+            return @prop_definitions if(!refresh && @prop_definitions_cached)
+            properties_site = File.join(self.class.site.to_s, "/projects/#{self.identifier}")
+            PropertyDefinition.site = properties_site
+            PropertyDefinition.user = self.class.user
+            PropertyDefinition.password = self.class.password
+            prop_defn_class = PropertyDefinition.send(:create_resource_class)
+            @prop_definitions = prop_defn_class.find(:all)
+            @prop_definitions_cached = true
+            @prop_definitions
+          end
+        end # module InstanceMethods
+      end # class Project
+    end # class V1
+  end # class API
+end

data/lib/mingle4r/api/v1/property_definition.rb

@@ -0,0 +1,16 @@
+module Mingle4r
+  class API
+    class V1
+      class PropertyDefinition
+        extend Mingle4r::CommonClassMethods
+
+        def self.column_name_for(prop_name)
+          property_def = @resource_class.find(:all).detect { |prop| prop.name == prop_name }
+          property_def ? property_def.column_name : nil
+        end
+      end
+    end
+  end
+end
+
+Mingle4r::API::V1::PropertyDefinition.element_name = 'record'

data/lib/mingle4r/api/v1/transition_execution.rb

@@ -0,0 +1,15 @@
+module Mingle4r
+  class API
+    class V1
+      class TransitionExecution
+        extend Mingle4r::CommonClassMethods
+        module InstanceMethods
+          def execute
+            conn = self.class.connection
+            conn.post(self.class.collection_path, encode, self.class.headers)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/mingle4r/api/v1/user.rb

@@ -0,0 +1,9 @@
+module Mingle4r
+  class API
+    class V1
+      class User
+        extend Mingle4r::CommonClassMethods
+      end
+    end
+  end
+end

data/lib/mingle4r/api/v1/wiki.rb

@@ -0,0 +1,12 @@
+module Mingle4r
+  class API
+    class V1
+      class Wiki
+        extend Mingle4r::CommonClassMethods
+      end
+    end
+  end
+end
+
+Mingle4r::API::V1::Wiki.collection_name = 'wiki'
+Mingle4r::API::V1::Wiki.element_name = 'page'

data/lib/mingle4r/api/v1.rb

@@ -0,0 +1,25 @@
+module Mingle4r
+  class API
+    class V1
+      def initialize(host_url)
+        @host_uri = URI.parse(host_url)
+      end
+      
+      def base_url
+        @host_uri.to_s
+      end
+      
+      def version
+        1
+      end
+      
+      def project_class
+        Project
+      end
+      
+      def user_class
+        User
+      end
+    end
+  end
+end