Recently, I wanted to start spinning up new projects in JIRA with some common epics and stories that we see on a lot of our projects. This seemed like a great way to capture some of the best practices and planning items that our teams have gathered over the years and ensure our teams can kick off consistently without starting from scratch.
Digging into the administrative tools, it didn’t seem like there were any import/cloning options in JIRA OnDemand to allow us to copy issues from one project to another. It looks like if you want to do this, you need to do it yourself!
Getting the integration working
I started off trying to find out how to integrate with OnDemand. There are both SOAP and REST APIs available, but the SOAP interface seems to no longer be the recommended path. That being said, I was trying to do something easy and wanted an easy way to integrate.
This brought me to the Atlassian.NET SDK. While limited because of being tied to the SOAP web service, it had all the pieces I needed for my simple cloning needs. With its simple connection creation and LINQ query support to work with issues collections, it had what I needed to do the simple integration.
SDK requires issues in the target project
One of the first road-blocks I ran into was that I could not create issues correctly if there wasn’t already an issue of that type in the target project. This meant I needed to create an empty Epic and an empty Story in the target project so that the SDK could properly instantiate custom fields and save the issues I was creating.
Not the biggest problem to face, but it was a bit of an annoyance.
Cloning Epics and Stories
The base project I wanted to clone is very simple, and the issues are only Stories and their associated Epics. No bugs, sub-tasks, attachments, comments, etc. From a cloning perspective, this means I have a fairly straightforward approach:
- Clone the Epics
- Clone the Stories
- Clone association of Story to Epic
When cloning the Epic items, the Epic issue type has a special field for the Epic Name. Similarly, Story items have a special field for the Epic Link. So when cloning the issue, we need to test for the issue type and the clone the appropriate fields. Both of these fields are treated as ‘custom fields’ in the Atlassian SDK.
Cloning the Epic Link
While the Epic Name is a straight value copy, the Epic Link is not as straight-forward. The source issue being cloned will reference the Epic from the source project, not the one that was cloned to the target project. This meant I needed to do some matching logic to find the matching Epic in the target project and create the new issue with an Epic Link reference to the matching target Epic.
Persisting Issue Rank
The piece that I had the most difficulty with was making sure any ranking done in the template project was maintained in the target project. With the SDK, I noticed it doesn’t handle custom fields that do not have names, and the rank field is one of those fields. I made a slight change to the SDK code to allow me to create a custom field with only an ID, but the API still wouldn’t save the value.
Apparently, this is a known issue with the SDK at the moment.
In the end, to ensure relative ranking was required, I needed to ensure the issues were imported in ranked order. This way, when JIRA auto-ranked the new issues, the values would have the same relative ranking as the template project. This can be accomplished by using a LINQ OrderBy expression and sorting on the custom field value for the rank field.
Some other things to consider
Other than the issue cloning, there are a few things you may want to do when cloning:
- Support configuration settings for connection information, source project key, and target project key.
- Add logic to delete issues before importing to allow for multiple runs to the same target project while testing.
- Provide the support for a ‘protection’ keyword that can be used to keep some issues from being deleted. Especially helpful for those ‘primer’ issues required by the SDK.
I hope this helped if you are looking to clone some issues for JIRA! Let me know if you need a hand getting started.