How to create a Sprint using the GreenHopper REST API

[Matt Doar]

I've worked out how to get the list of boards, the list of sprints, the issues in a sprint, create a new board and add issues to a sprint. The last thing I'm stuck on is creating a sprint using GH REST. Using the rest browser and looking in the Chrome developer network tab I see various calls:

1. backlog/markers/add with {"rapidViewId":4} is called when I click Create Sprint
2. sprint/create/model is called after that?
3. sprint/create is called when I click Start Sprint

What I'm using all this for is migrating data from one JIRA instance to another, so I really just want to create a sprint using the same data as an existing sprint in another JIRA.

So, if you know how the GreenHopper REST API is supposed to be used to create sprints, please tell us all! This is GH 6.1.5

~Matt

[Bill Marten]

If you know your rapid-board id, then you can create a new unstarted sprint by calling a POST request with:

http://<JIRA-server>/rest/greenhopper/1.0/sprint/<rapid-board-id>

(with no data attached)

Works as of JIRA Agile v6.3.6

[Mikhail T]

Bill, what will the name of the new sprint be after that?

[Bill Marten]

It'll be the Sprint that follows your previous one, i.e. if your last sprint was 'Sprint 32', the new one will be 'Sprint 33'.

You can then rename it to whatever you like of course.

[Matt Doar]

Here's what I've worked out. A board shows a list of issues. You order the issues. Creating a sprint is just a marker in that list of issues and you move issues up and down the list to make them appear below a marker. Markers have no dates and do not appear in the list of sprints. It's when you start a sprint it becomes an actual object including dates.

The problem I've run into with recreating GH data in another JIRA instance is that neither the UI nor the API let you add issues to completed sprints. So there's no easy way I can see to reproduce the history of a board, and I can only reproduce the current sprint(s).

I guess moving GH data is going to have to involve reading an activeobjects.xml file and inserting the data into the target database after some suitable tweaks to account for different project ids, sprint ids etc.

The other odd thing I've noticed is that if I define a board for project FOO, add some sprints and issues, then delete the board. The next time I create a board for the same project all the sprints are still there! Weird.

[sclowes]

I'd suggest just taking a look at the GreenHopper code Matt, there's no better documentation than the code itself.

A sprint that has not been started is a marker, (i.e. backlog/markers/add), it's a ranked item in the backlog. A sprint is created (i.e. started) with /rest/greenhopper/1.0/sprint/create. Issues are added to the sprint by editing the Sprint custom field in the issues to contain the sprint (specifically it's ID).

Cheers,
Shaun

[Matt Doar]

Yup, I'm in the code (there's no other way to find out what parameters to pass to the REST resources). But in the end the GH REST API doesn't have a way to add issues to closed sprints, so I can't use it to recreate GH data from one JIRA in another JIRA. So it's got to be either the GH Java API or SQL inserts.

[sclowes]

You're right, there's no way to assign an issue to a closed sprint from the UI. You'll need to edit the sprint custom field and create a back dated issue history entry to the issue to show that the sprint field was added to the issue before or during the sprint timeframe. You can't do backdating from the REST endpoints so you will need to use a Java plugin.

Please don't tweak the activeobjects.xml. Why not do something using the JIRA Importer (JIM) and the JSON import format (which is how the GreenHopper sample data itself is implemented). Take a look at https://bitbucket.org/nmuldoon/greenhopper-sample-data which is a Groovy script that can be run in Script Runner which I wrote a while ago which demonstrates how you can import issues in to historical sprints.

Cheers,
Shaun

[Matt Doar]

Good idea, thanks.

[Matt Doar]

Using that idea, I've managed to successfully move Sprint information from one JIRA instance to another. This assumes that a JIRA project has already been imported into a new JIRA instance.

For the GH migration first a python script gets the list of all sprints for a chosen board, including the completed and incomplete issues. All that data is written to a local json configuration file. Then a groovy script is run in the target JIRA to recreate the sprints. These new sprints now have different ids so the groovy script goes through all the issues related to a sprint and updates the sprint field and then fixes the issue history so that it looks like the sprint was set to the correct id at the appropriate time.

This all works because the issue history of a project imported issue still contains all the history about the sprint field. Quite the exercise. I guess it could be done more elegantly in a GH admin tab.

[DI2E Licensing]

Matt, can please you share the scripts you created for doing this?

[Sorin Sbarnea (Citrix)]

Here is a feature request for solving the mess around working with sprints using the REST API:

https://jira.atlassian.com/browse/GHS-10848

The GH/Agile REST API related to Sprints is unstable and unecessarly complex. This bug is requesting a fix on it, so people can use it to automate the process, or to enable migrations from other systems.

At this moment, you can edit sprints but not their Status, even so the process of creating and editing them is anything but not simple.

[Bill Marten]

Yes see below...

"If you know your rapid-board id, then you can create a new unstarted sprint by calling a POST request with:

http://<JIRA-server>/rest/greenhopper/1.0/sprint/<rapid-board-id>

(with no data attached)

Works as of JIRA Agile v6.3.6"

[Sorin Sbarnea (Citrix)]

Did anyone managed to find out how to add a sprint using REST ?! Agile 6.3+

Python-jira create_sprint() is broken, probably because atlassian removed the create verb.

[codelab expert]

You can try to use this POST message (e.g.):

https://jira.atlassian.com/rest/greenhopper/1.0/sprint/create

[Matt Doar]

No, I think that's just used when the sprint is started.

[Mikhail T]

After installing the REST API Browser plugin, I can see the API-calls available in my JIRA instance. There are several calls listed under greenhopper/1.0/sprint/, but, unfortunately, greenhopper/1.0/sprint/create is not among them... Any idea, why? Our JIRA is a recent 6.1.7.

Thank you!

[MattS]

Take a look at the source code for jira-python where I added methods to do this after I worked out some of the REST calls

[Mikhail T]

Matt, searching for "jira-python" I find a lot of links, that are seemingly unrelated with each other. Could you, please, link to what you are talking about? Thanks!

[Mikhail T]

Ok, I found your library and the function create_sprint() in it. However, it seems to me, you are relying on that same sprint/create call, that does not appear to exist in our JIRA version (6.1.7). Or am I misreading your code -- it's been a while since I last wrote a Python script, unfortunately...

Yep, I just tried rewriting my TCL script in Python so I could use your library -- and the create_sprint() function does not work. Here is the relevant HTTP exchange between my computer and the JIRA server as captured with tcpdump:

Request:

POST /jira/rest/greenhopper/1.0/sprint/create HTTP/1.1
Host: jira:8080
Content-Length: 63
Accept-Encoding: gzip, deflate, compress
Accept: */*
User-Agent: python-requests/1.2.3 CPython/2.7.5 FreeBSD/9.2-STABLE
Cookie: JSESSIONID=AC_xxx_B08B; atlassian.xsrf.token=BGWC-xxx-581d|lin
Authorization: Basic fooo

{"rapidViewId": 20, "name": "2012-OCT-31", "sprintMarkerId": 0}

Response:

HTTP/1.1 404 Not Found
Server: Apache-Coyote/1.1
X-AREQUESTID: 1274x14698x1
X-ASESSIONID: muXXXp
X-Seraph-LoginReason: OK
X-AUSERNAME: mXXXX
Cache-Control: no-cache, no-store, no-transform
X-Content-Type-Options: nosniff
Content-Type: text/html;charset=UTF-8
Transfer-Encoding: chunked
Date: Tue, 22 Apr 2014 01:14:05 GMT

d47
....

Because it is a 404, I conclude, the problem is in that this particular REST endpoint is just not implemented here.

I'm afraid, the sprint/create is not as widely available as it should be... Thank you!

[MattS]

Hmm. I know JIRA Agile changed how a non-started sprint is tracked a few releases ago. Perhaps the change has broken the jira-python code. What version of JIRA and JIRA Agile are you using?

[Mikhail T]

We are using JIRA-6.1.7 (the latest in 6.1.x AFAIK) with Agile 6.3.7, that comes bundled with that.

I just checked, there is an upgrade for Agile to bring it to 6.3.12 -- I'll try upgrading our dev-instance to see, if that adds the missing method.

Nope, after the upgrade of JIRA Agile to 6.3.12 I still get a 404, when attempting to use the sprint/create REST API call.

[Mikhail T]

I wonder, if I can INSERT the new sprint-names directly into the AO_60DB71_SPRINT-table -- not with the REST API, but using SQL?

[Pedro Cora]

Matt,

Take a look in the Developer Toolbox https://jira.atlassian.com/plugins/servlet/restbrowser#/com-pyxis-greenhopper-jira-greenhopper-rest-filter that may help.

Cheers,

Pedro

[Matt Doar]

The restbrowser is how I got the other methods working. But there's not enough documentation to make it clear which methods to use or what parameters to pass in. At the moment it's like reading an index in a book to try to understand the plot!