github.com/arusarka/mingle4r/tree/master

This gem is a wrapper around active resource to access the rest api exposed by mingle (thoughtworks-studios.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. The typical use-case for this gem is to help someone getting started with writing code to integrate with 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.

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

It gives you access to projects in the mingle instance, cards under the project and also attachments for a particular card.

This library is a wrapper around active resource to interact with Mingle easily. So before using this gem a good idea would be to get familiar with active resource and the mingle apis. If you have a mingle server running somewhere you can check the different apis at <server address>/help/mingle_api.html or goto www.thoughtworks-studios.com/mingle/3.0/help/mingle_api.html

A lot of examples are given below to get you started.

Current version under development (0.5.0 ) will support Mingle 3.5.

The api now supports only mingle 3. Mingle 2 is no longer supported. If you need to connect to both Mingle 2 and Mingle 3 then try 0.3.0 of the gem.

In all the documentation below you can replace Mingle4r::MingleClient with MingleClient. Its an alias for easy use.

Suppose you want to connect to the mingle instance hosted at 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 => array of active resource objects

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 ‘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 => active resource object
		
2. Set an attribute later
    m_c = Mingle4r::MingleClient.new('http://localhost:8080', 'testuser', 'password')
    m_c.proj_id = 'great_mingle_project'
    project = m_c.project

m_c.valid_credentials? => returns true or false

Get a mingle client object. Then call the cards method.

m_c = Mingle4r::MingleClient.new('http://localhost:8080', 'testuser', 'password')
m_c.proj_id = 'great_mingle_project'
m_c.cards => array of activeresource objects

Alternatively you can also do
  m_c.project.cards => array of activeresource objects

m_c.find_card(42) => card activeresource object

Alternatively you can also do
  m_c.project.find_card(42)

Mingle allows a lighweight implementation of sql called mql through which you can filter cards. Look at www.thoughtworks-studios.com/mingle/3.0/help/mql_reference.html for reference. However when using this feature you should only give the condition not the properties you want out of mingle.

m_c.filter_cards('Type IS Story') => returns a list card objects

Do not do this (it simply *won't work*) :
  m_c.filter_cards('SELECT number, type WHERE Type IS Story')

If you want to execute a generic mql look at the 'MQL Execution' section

m_c = Mingle4r::MingleClient.new('http://localhost:8080', 'testuser', 'password')
m_c.proj_id = 'great_mingle_project'
card = m_c.cards.first
card.custom_properties => returns an array of hashes, {property name => property value}

However this gives only custom properties, not all the properties.

gets the value of a property. The property name given should be the same as seen in Mingle. Type, name, description and number of a card can be accessed directly. For any other custom property use the method below.

m_c = Mingle4r::MingleClient.new('http://localhost:8080', 'testuser', 'password')
m_c.proj_id = 'great_mingle_project'
card = m_c.cards.first
card.property_value('Status')

sets the value of the property. The property name given should be the same as in Mingle. Type, name and description should be set directly when creating or updating a card. In case of a custom property use the following method. 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.find_cards('Type IS Defect').first
defect_card.property_value('Status', 'Closed')
defect_card.save

In case of properties of type ‘Tree Relatioship property’ or ‘Card’(properties which link to another card) you can should set the property by giving the number of the card. For e.g.

story_card = m_c.projects.cards.find {|c| c.type == 'Story'}.first
story_card.property_value('Feature', 12)
story_card.save

In case of properties of type ‘Team member’ you can either use the user id (not the name or the login id, you would have to look at the xml to get the id) or more simply the user name. For e.g.

story_card.property_value('Assignee', 'James Bond')
story_card.save

MingleClient provides a handy method to create a new card.

task = m_c.new_card
task.name = 'set up Cruise build'
task.type = 'task'
task.description = 'a basic cruise build needs to be set up so that we can start working'
task.save

Alternatively you can also do:
  Mingle4r::API::Card.site = 'http://localhost:8080/projects/agile/'
  Mingle4r::API::Card.user = 'foo'
  Mingle4r::API::Card.password = 'bar'

  task = Mingle4r::API::Card.new , rest of the steps are same as above

Do not do it like this:

task = m_c.new_card :name => 'set up Cruise build', :type => 'task',
            :description => 'a basic cruise build needs to be set up so that we can start working'
task.save => It simply won't work, there is a workaround but rather use as described above.

Mingle maintains the different versions of a card. It always shows the latest version by default. However if you want to access a different version you can do so in the following ways.

m_c = Mingle4r::MingleClient.new('http://localhost:8080', 'testuser', 'password')
m_c.proj_id = 'great_mingle_project'
defect_card = m_c.find_card(20)

supposing the latest version of the card is 42

1. Get the previous version
    defect_card.version(:previous) # return version 41

2. Get the next version
    defect_card.version(:next) # returns version 42 since it is the latest version

3. Get an arbitrary version
    defect_card.version(21) # returns version 21

m_c = Mingle4r::MingleClient.new('http://localhost:8080', 'testuser', 'password')
m_c.proj_id = 'great_mingle_project'
defect_card = m_c.find_cards('Type IS Defect').first
defect_cards.comments

m_c = Mingle4r::MingleClient.new('http://localhost:8080', 'testuser', 'password')
m_c.proj_id = 'great_mingle_project'
defect_card = m_c.find_card(420)
defect_card.add_comment('Not able to reproduce')

m_c = Mingle4r::MingleClient.new('http://localhost:8080', 'testuser', 'password')
m_c.proj_id = 'great_mingle_project'
defect_card = m_c.find_cards('Type IS Defect').first
defect_card.attachments

1. Downloading a particular attachment
    attachment = defect_card.attachments.first
    attachment.download('page.css')

2. Uploading an attachment
    defect_card.upload_attachment('page-screenshot.jpg')

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 = m_c.cards.first
    card.murmurs

3. post a murmur(hooray!)
    project.post_murmur('my first murmur, I am excited!')

m_c = Mingle4r::MingleClient.new('http://localhost:8080', 'testuser', 'password')
m_c.proj_id = 'great_mingle_project'
defect_card = m_c.cards.first

defect_card.transitions # array of active resource objects

m_c = Mingle4r::MingleClient.new('http://localhost:8080', 'testuser', 'password')
m_c.proj_id = 'great_mingle_project'
defect_card = m_c.find_cards('Type IS Defect').first

defect_card.execute_transition(
 '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, multiple properties might need to be set.
)

mingle allows you to write an arbitrary MQL query and returns the results. This gem allows you to do that in a simpler way. If you want to know more about MQL go to www.thoughtworks-studios.com/mingle/3.0/help/mql_reference.html.

m_c = Mingle4r::MingleClient.new('http://localhost:8080', 'testuser', 'password')
m_c.proj_id = 'great_mingle_project'
m_c.project.execute_mql('SELECT name, "Added in Iteration" WHERE Type = Story') 
  => returns an array of hash

1) active_resource gem, it would be automatically taken care of during gem install.

creating a card with custom properties directly doesn’t work.

since github no longer archives gems, I am hosting the gem at gemcutter. So you would need to add gemcutter.org to your gem sources : gem sources -a ‘gemcutter.org’. Then do

gem install mingle4r

(The MIT License)

Copyright © 2010 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.