Vladimir.Dyuzhev - Test Director To JIRA Sync

What it is and How it works

This is a small application that allows developers (who use JIRA issue tracker) and QAs (who use Test Director/Quality Center 9) to synchronize issues and comments. Typically during SIT or UAT cycle QAs record found issues in TestDirector, and developers should take care of them. But developers prefer to use JIRA (which is superior as a developer's tool). Developers have workflows defined in JIRA. Developers also don't want to share all the internal communication happening during issues resolution (in fact, TD has a limit for dev comments field, so extensive conversations could not be stored in TD). TD2JIRA allows QA work with TD, and developers work with JIRA, while having the same issues information.

When TD2JIRA runs, it loads all the issues from specified TD project, and finds (or creates) a corresponding issue in JIRA project. New TD comments get copied into JIRA issue. New TD file attachments get copied into JIRA too. Specially marked JIRA comments (those that should be read by QA) are copied back into TD. TD2JIRA also updates AssignedTo field in TD to bring it in sync with JIRA, so management can see who's working on a particular task.

Only the issues created in TD get pushed into JIRA, not the other way around. It's TD2JIRA, not JIRA2TD.

TD2JIRA has a (primitive) rule-engine built-in, so every team can adjust the logic according to their workflow and requirements.

N.B. To track TD-based JIRA issues, TD2JIRA uses Summary prefix. By default, it's "DEFECT", so if we have a TD issue 123 with summary "A Bug", then JIRA issue would have a summary "DEFECT 123: A Bug". Please choose your prefix (jira.summary.prefix property) to be unique enough for a full-text search.

Download

Latest version can be taken from SVN.

Despite I myself don't do the development anymore, those in need :) enhance td2jira and do some bugfixing.

Installation

TD2JIRA runs only on Windows. Not my fault: TD remote interface is DCOM, and the only (free) way to talk DCOM from Java is to use native calls on Windows platform. Sorry.

TD2JIRA is distributed as an ant-based Java project. Default target is to start synchronization (a.k.a. ant sync). Once started, it will perform it's duty forever, with 5 min sync interval (by default).

There is a file called td2jira.properties, which can be modified to adjust to your environment. By default the file defines a fake TD project (a mock) connected to jira.atlassian.com TST project:

# JIRA connection data
jira.url=http://jira.atlassian.com
jira.user=myid
jira.password=mypassword
jira.project=TST

but the jira.user and jira.password are not valid -- you'll have to register on http://jira.atlassian.com to make it work. TD settings, although specified in the property file, are not in effect because of another property:

# TD connection Implementation
td.implementation=td2jira.td.api.mock.Connection

This means that instead of connecting to "real" TD installation, TD2JIRA will generate TD issues internally, add comments and attachments to them, and walk them through workflow. This mode helps to play with TD2JIRA and your environment before bothering QA team. I recommend you to setup an empty test project in JIRA, and point TD2JIRA with mock connection there. When you're sure all information is propagated correctly (no duplicate issues or comments, files are not corrupted, ...) you may try connect TD2JIRA to real TD, still pointing to the test JIRA project (better create another, clean, one). And only when it's still OK, move into real-TD-to-real-JIRA mode.

There are a plenty of other configuration properties in td2jira.properties, but they are either self-describing, or have comments, so I'll skip them altogether.

Default Rules

There is a set of rules that comes with the distribution. These rules are not the best by any means, these are just the rules used in the company I'm currently working for. Nevertheless, I'll describe those rules here to give you an example:

1. class=td2jira.sync.impl.SyncIssues;
2. class=td2jira.sync.impl.SyncAttachments;
3. td.status=Closed|Rejected,jira.status=Open|Assigned To Fix|Assigned To Merge|Assigned To Review|Resolved,class=td2jira.sync.impl.CloseJiraIssue;
4. td.status=Reopen|Assigned,jira=null,class=td2jira.sync.impl.CreateJiraIssue;
5. td.status=New|Open|Reopen|Assigned,jira.status=Resolved,class=td2jira.sync.impl.MarkTdIssueAsFixed; 6. td.status=Reopen|Assigned,jira.status=Closed,class=td2jira.sync.impl.RecreateJiraIssue;
7. td.status=Fixed,jira.status=Closed,class=td2jira.sync.impl.AskToRetest;

which means:

sync issues comments first (regardless ofl statuses)
sync attachments (from TD issue to JIRA issue)
if TD issue is Closed or Rejected, and JIRA issue is Open or Assigned or ... then close JIRA issue
if TD issue is Reopened or Assigned, and no JIRA issue found, create JIRA issue
... and so on

Basically, it's a simple rule engine. You may create your own handlers (implementing td2jira.sync.impl.IProcessIssuePair). See existing implementations for details.

Two ways to access JIRA

JIRA has SOAP and XML-RPC interfaces. Despite SOAP API is much more powerful, the default for TD2JIRA is XML-RPC. The reason is that SOAP API is not compatible among even minor versions of JIRA (new methods, new fields in types), while XML-RPC works almost always. In light of mentioned below bug with addAttachmentsToIssue, there is no real reason to use SOAP out of the box until Atlassian stabilize their SOAP API for major operations.

The access mode is switched by the property:

# Connector Implementation
jira.connector.implementation=td2jira.jira.xmlrpc.JIRAXmlRpcConnector
# jira.connector.implementation=td2jira.jira.soap.JIRASoapConnector

Limitations

Current version (1.0) doesn't support copying attachments via SOAP. Instead, it does a HTTP POST to AttachFile JSP. The reason is twofold. First, the JIRA WSDL file seems to be incorrect, and uses byte[][] instead of base64-encoded files. In fact, modern WS tools (including JAXB and .NET 2.0) refuse to compile the WSDL. Axis 1.4 happily compiles it though, but (it's the second reason) resulting message is enormous in size (700K for 3K file, grows proportionally). Hence, the WSDL's addAttachmentToIssue() method is unusable.

F.A.Q.

Q1. Does TD2JIRA support HTTP proxy?

A1: It does. In fact, it even supports proxy authorization. I failed to use NTLM authentication in attach file though. The request comes through, it looks like, but something is still wrong, and JIRA fails.

Q2: How to make TD2JIRA copy a comment from JIRA to TD?

A2: Provide a "2qa:" prefix to your comment. TD2JIRA will create a matching comment in TD. To assign the task to someone in TD use "2qa:tduserid", like here:

2qa: Please retest
2qa:johnmk This works as documented, please reject

In fact, it's a hackish way. The Right Way (tm) would be to check the JIRA comment group (visible to developers, ...) and copy it to TD if it's visible to everyone. It's not hard to do. Anyone?

Q3: Can TD2JIRA be used to sync TD and/or JIRA with <insert your legacy tool here>?

A3: Not out of the box. But the logic and design (well, it's too simple for calling it "architecture") of the application can be used as a template for creating similar tools (or even plugging in more target applications into TD2JIRA itself).

Support

No support whatsoever. I can answer some general questions, but don't expect me to modify TD2JIRA for your needs. You're developers, figure it out yourselves!

License

BSD-Style:

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Author

This software was designed and implemented by me, Vladimir Dyuzhev. Feel free to email me.