This version of the Mingle-JIRA Connector is deprecated in favour of a new release. Please see this post for details.

The Mingle- Jira connector enables Mingle, your project management and collaboration platform and Jira, your issue tracker to interact with each other as a part of your teams' natural workflow. Thus collaborating teams can create, manage, and track bugs, issues and feature requests in their respective Mingle or Jira instance, with the connector mapping changes across the systems. This provides a cohesive integration of bug and feature progress in JIRA, with Mingle’s Agile project management platform. This centralized visibility facilitates scheduling, tracking and management, with minimal effort and configuration.

The Mingle-JIRA Integration enables you to:

• Automatically create Agile stories or defects in Mingle to manage feature requests or bugs created in Jira.
• Automatically sync defect or story status and progress between Mingle and Jira.
• Get traceability of story/defect activity and progress between management, dev, QA and Operations teams.
• Automatically create bi-directional links between JIRA feature requests/bugs and Mingle story cards/defects.
• Be alerted of changes in defects and features in Mingle via Email/RSS subscriptions.
• Centrally manage, track and report defects and feature requests in JIRA using Mingle’s advanced reporting capabilities, Macro toolkit and multiple dashboard support.

Known limitations of this software are documented in the Release Notes.

Operation

The Mingle-JIRA Connector allows issues to be passed from JIRA toMingle. A new card is created in Mingle for each issue that is passed.Each of the cards created in Mingle will include a link back to theJIRA issue from which it originated. The cards also have a propertyholding the key of the JIRA issue.The JIRA issue will be updated to have fields holding the URL of thecard in Mingle and its current status.Any changes made to an issue in JIRA will result in a comment beingadded to the corresponding card in Mingle.

There are four ways to pass issues from JIRA to Mingle:

1. Manually pass a bug by triggering a workflow action
2. Manually pass a feature request by triggering a workflow action
3. Automatically pass all issues that match an arbitrary filter as bugs
4. Automatically pass all issues that match an arbitrary filter as stories

The Connector can be configured to match the way your projects areorganized. The card types, issue types, Mingle fields and JIRA properties are all configurable.

Supported Platforms

• CentOS 5.4, MS Windows 2003 Server, Ubuntu 9.10
• Java 1.6
• Mingle 3.2-3.3
• JIRA 3.12.3, 3.13.2 and 4.1.1

Administration

Logging

By default the Connector logs at WARN level to mingle-jira-connector.log in theinstallation directory.ERROR level logs indicate a problem handling an individual Mingle cardor JIRA issue. FATAL level logs indicate problems that stop theapplication from working.If you set the logging level to WARN, you will see summary informationeach time the Connector is run. If you set it to INFO level, you willsee details of each event handled.

Email archive

The Connector operates by reading emails from a dedicated mailbox. Allemails that have been read and successfully processed are moved intothe HANDLED folder. Any emails that caused an error are moved to theERROR folder. If the error condition has been fixed then events can bereplayed by moving the emails back into the INBOX.

Installation

• Download the Windows or Linux installer.
• Extract the tarball or the zip archive into the directory where you  want to install the Connector (the archive extracts into its own  subdirectory).
• Enter your system's configuration details in a file  mingle-jira-connector-config.yml in the installation directory (see the  section Configuring the Connector for details).
• Configure Mingle and JIRA (see the sections Configuring JIRA and  Configuring Mingle for details).
• Set up a scheduler such as cron or the Windows scheduling service to  run the Connector every half an hour. It should invoke  mingle-jira-connector.sh or mingle-jira-connector.bat without arguments.
• The Connector needs to be run with sufficient permissions to write  to the installation directory and to the log file location (if that  is configured to be elsewhere).

Configuration

Configuring email

This application needs a dedicated email account with IMAP or IMAP-SSLaccess. The Connector will create the folders that it uses.

Configuring JIRA

Server configuration

• Configure JIRA to send mail to the mail server.
• Configure two custom fields that can be used in all issue types that  will be passed to Mingle: one of type 'Text Field' to hold the  development status and one of type 'URL' to hold the URL of the card  created in Mingle. Note the ids of these custom fields, which are  needed for configuring the Connector (the id can be seen in the URL  of the field config screen).
• Ensure that the JIRA base url property is set to the JIRA server's  url (under General Configuration > Settings).
• Ensure that the 'Accept remote API calls' setting is set to ON (under  General Configuration > Options)

User configuration

• Create an account in JIRA which will be used by the Connector.
• Set the user's email address to the one created for the Connector.
• Give the user permission to edit issues.
• Modify the project's Notification Scheme so that the user receives  email notification of the following events:
  • Issue Updated
  • Issue Commented
  • Issue Comment Edited
• Configure the user to receive emails in html format.
• Configure the user to have a locale English (United States).(Email format and locale must be configured by logging in as the user inquestion and navigating to Preferences.)

Passing issues to Mingle

There are four different ways to pass issues to Mingle: passingindividual bugs, passing individual feature requests, passing bugsbased on a filter and passing features based on a filter. You may choosewhich of these to use; at least one must be configured for the Connectorto work.

Passing individual bugs

Configuring JIRA to allow the passing of individual bugs creates aworkflow action link on each relevant issue. Clicking the link causesthe issue to be passed to the development team as a bug.To configure this:* set up the email template bugtomingle.vm (found in the Connector's  resources directory)* create a Pass Bug to Dev event with the associated notification* add the event to your project's workflowDetails of these steps appear in the following section "Details ofJIRA configuration".

Passing individual feature requests

 Configuring JIRA to allow the passing of individual feature requestscreates a workflow action link on each relevant issue. Clicking thelink causes the issue to be passed to the development team as afeature request or story.To configure this:* set up the email template featuretomingle.vm (found in the  Connector's resources directory)* create a Pass Feature to Dev event with the associated notification* add the event to your project's workflowDetails of these steps appear in the following section "Details ofJIRA configuration".

Passing bugs based on a filter 

Configuring JIRA to pass bugs based on a filter causes all issuesmatching the filter to be automatically passed to the development teamas bugs, without any manual intervention.To configure this, set up a subscription for the filter which sends anemail to the the Connector's user every 30 minutes. The name of thefilter must be added to the Connector config file under jira:bug_filter(see Configuring the Mingle-JIRA Connector below).

Passing features based on a filter Configuring JIRA to pass features based on a filter causes all issuesmatching the filter to be automatically passed to the development teamas stories, without any manual intervention.To configure this, set up a subscription for the filter which sends anemail to the the Connector's user every 30 minutes. The name of thefilter must be added to the Connector config file under jira:story_filter(see Configuring the Mingle-JIRA Connector below).

Details of JIRA configuration


Setting up an email template 
* Copy the mail body template into your JIRA installation, in the directory  atlassian-jira/WEB-INF/classes/templates/email/html.* Copy the mail subject template into your JIRA installation, in the directory  atlassian-jira/WEB-INF/classes/templates/email/subject only if you are using jira 4 or above.* Modify the template mappings config file  (atlassian-jira/WEB-INF/classes/email-template-id-mappings.xml) to  include a <templatemapping> element for these templates.** the id attribute must be unique in the file (it should be safe to   choose a number higher than 10000)** <name> can be the same as the file name** <template> must be the file name** <templatetype> should be issueevent* Restart JIRA.




Creating an event and notification 

Create an event which uses the email template that you haveconfigured. The name of the template that you set up will appear inthe list of options for the new event.Modify your project's notification scheme to add a notification forthe new event. It must be a "Single User" notification for theConnector's user.




Adding an event to project workflow 


These instructions assume that you are using JIRA's defaultworkflow. If your project uses a different workflow then you will needto adapt the instructions accordingly.
* Copy JIRA's default workflow.* Modify the new workflow's steps, adding a transition to the "In  Progress" step.** name the new transition "Pass Bug to Dev" or "Pass Feature to Dev",   as appropriate** make the destination stop "In Progress"** click on the new transition to edit it and modify the event fired   by the Post Functions to be the event that you created in the   earlier step* Create a new workflow scheme.* Within the new scheme, assign your modified workflow to all (or just  the relevant) issue types.* Assign the new workflow scheme to your project.These instructions create a very simple workflow. You may wish toadopt a more complex workflow which assigns a specific state to issueswhich are being worked on by the development team.If you are modifying an existing custom workflow, note that you cannotmodify a workflow or workflow scheme which is assigned to aproject. The easiest thing to do is to copy the existing workflow andscheme, modify them and then associate them with the project.



Configuring Mingle


These instructions assume that the development team is already using Mingle and has a project configured. If this is not the case then youwill need to create a project in Mingle. See the Mingle documentation for details.

• Create an account in Mingle for the Connector to use. It should be a  full member of the project.
• The Connector's user in Mingle should have the same email account as  its user in JIRA.
• Basic Authentication must be turned on for your Mingle instance. See  Mingle API documentation for details.
• Add a property of type 'any text' to the project. This property will  hold the JIRA issue key for cards that are created by the Connector.
• Assign this property to the card types that the Connector will  create.
• Set up a history filter for the project on behalf of the Connector's  user, that sends out email notifications for all changes to cards of  the types that will be created by the Connector.

Configuring the Connector

Configuration should be placed in mingle-jira-connector-config.yml in theinstallation directory. There is an example configuration file atresources/mingle-jira-connector-config.example.yml).The configuration file is in YAML format(http://www.yaml.org/start.html). This means that some valuescontaining special characters (e.g. '!') need to be placed in quotes.Email::  details of the mail server and the Connector's email account; for  IMAP-SSL access, the protocol must be specified as 'imaps'. Protocol  defaults to 'imap'.Mingle::  details of the server, user, project identifier, card types to  create, status properties and JIRA issue key property; the hostname  given must be globally applicable in the network; bug_type is the  type of card that will be created in Mingle when a Bug is passed,  story_type is the type of card that will be created in Mingle when  a Feature Request is passed.Logging::  log file location (defaults to mingle-jira-connector.log in the  Connector's installation directory) and the logging level (defaults  to WARN)JIRA::  details of the server, user, custom fields and any filters  configured; custom fields must be identified by their numeric ids,  filters must be identified by their names (see section above  "Configuring JIRA").

Note: By default the Connector communicates with Mingle only via HTTP. If  your Mingle server requires the use of HTTPS, then you need to give  the port as 443 and add the protocol as https.

Appendix

* The help pages for Mingle 3.1 is available at:  http://www.thoughtworks-studios.com/mingle/3.1/help/index.html
* The help pages for Mingle 3.0 is available at:  http://www.thoughtworks-studios.com/mingle/3.0/help/index.html
* The help pages for JIRA 3.12.3 is available at:  http://www.atlassian.com/software/jira/docs/v3.12/
* The help pages for JIRA 3.13.2 is available at:  http://www.atlassian.com/software/jira/docs/v3.13/* The help pages for JIRA 4.1.1 is available at:  http://confluence.atlassian.com/display/JIRA/Home