A while ago I described how to get release notes from JIRA with Groovy, so I thought it’s time to do a small follow up which is long overdue :-).
Let’s split things up to manageable classes with their own responsibility:
- a JIRA REST client which encapsulates connecting to my JIRA instance, such as (HTTP) getting or posting from and to an url while using the proper credentials
- a JIRA query builder, responsible for building JQL snippets to be used for the JIRA search REST API
We’ll start at the bottom, so we’ll build upon the classes we already have.
Just Being Typesafe
Although a lot of the date we’re getting back from JIRA can be used as-is in Groovy, I decided to make the status of a JIRA issue, e.g. “Open”, into a trivial enum.
enum JiraStatus {
OPEN("Open"), IN_PROGRESS("In Progress"), RESOLVED("Resolved"), REOPENED("Reopened"), CLOSED("Closed");
JiraStatus(String value) { this.value = value }
private final String value
String value() { return value }
}
I’ll stick to Strings in the remainder of this post 🙂
Building a JQL Query
Queries you can execute within JIRA itself in the Issue Navigator can also be performed through the REST API. Because there are several elements which constitute a JQL-query I decided to use the builder pattern to programmatically create queries through the JiraQueryBuilder.
import groovyx.net.http.RESTClient
import JiraStatus
/**
* Builder for a JQL-snippet, used for the JIRA search REST API.
*/
class JiraQueryBuilder {
private String project
private int[] sprintIds
private String sprintFunction
private String[] issueKeys
private String[] issueTypes
private String[] excludedIssueTypes
private String[] resolution
private JiraStatus[] status
private String[] labels
private String fixVersion
private String orderBy
/**
* Create a new query builder, querying by default everything for specified project, ordered by key.
*/
public JiraQueryBuilder(String project) {
assert project
this.project = project
withIssueTypes("standardIssueTypes()")
withOrderBy("key")
}
JiraQueryBuilder withSprintIds(int...sprintIds) {
this.sprintIds = sprintIds
return this
}
JiraQueryBuilder withIssueKeys(String...issueKeys) {
this.issueKeys = issueKeys
return this
}
JiraQueryBuilder withIssueTypes(String... issueTypes) {
this.issueTypes = issueTypes
return this
}
JiraQueryBuilder withExcludedIssueTypes(String... excludedIssueTypes) {
this.excludedIssueTypes = excludedIssueTypes
return this
}
JiraQueryBuilder withResolution(String... resolution) {
this.resolution = resolution
return this
}
JiraQueryBuilder withStatus(JiraStatus... status) {
this.status = status
return this
}
JiraQueryBuilder withLabels(String... labels) {
this.labels = labels
return this
}
JiraQueryBuilder withFixVersion(String fixVersion) {
this.fixVersion = fixVersion
return this
}
JiraQueryBuilder withOrderBy(String orderBy) {
this.orderBy = orderBy
return this
}
String build() {
String jql = "project = ${project}"
if (sprintIds) {
jql += " AND sprint in (${sprintIds.join(',')})"
}
if (sprintFunction) {
jql += " AND sprint in ${sprintFunction}"
}
if (issueKeys) {
jql += " AND issuekey in (${issueKeys.join(',')})"
}
if (issueTypes) {
jql += " AND issuetype in (${issueTypes.join(',')})"
}
if (excludedIssueTypes) {
jql += " AND issuetype not in (${excludedIssueTypes.join(',')})"
}
if (status) {
// turn (IN_PROGRESS, RESOLVED) into (Resolved, In Progress)
jql += " AND status in (${status*.value().join(',')})"
}
if (resolution) {
jql += " AND resolution in (${resolution.join(',')})"
}
if (labels) {
jql += " AND labels in (${labels.join(',')})"
}
if (fixVersion) {
jql += " AND fixVersion = \"${fixVersion}\""
}
if (orderBy) {
jql += " order by ${orderBy}"
}
return jql
}
}
Connecting to JIRA
Finally I needed to encapsulate the connection to a JIRA instance, allowing me to (HTTP) GET and POST from and to it, including using the proper credentials.
// require(groupId:'org.codehaus.groovy.modules.http-builder', artifactId:'http-builder', version:'0.5.2')
import net.sf.json.groovy.*
import groovyx.net.http.RESTClient
import static JiraStatus.*
/**
* JIRA REST client wrapper around groovyx.net.http.RESTClient
*/
class JiraRESTClient extends groovyx.net.http.RESTClient {
private static final String DEFAULT_PROJECT = "XXX"
private static final String DEFAULT_SEARCH_URL = "http://jira/rest/api/latest/"
String username
String password
def credentials = [:]
/**
* Create a REST client using Maven properties jira.username and jira.password for JIRA username and password.
*/
static JiraRESTClient create(def project) {
String jiraUsername = project.properties['jira.username']
String jiraPassword = project.properties['jira.password']
if (!jiraUsername?.trim()) {
throw new IllegalArgumentException("Empty property: jira.username")
}
if (!jiraPassword?.trim()) {
throw new IllegalArgumentException("Empty property: jira.password")
}
return create(jiraUsername, jiraPassword)
}
/**
* Create a REST client using provided JIRA username and password.
*/
static JiraRESTClient create(String username, String password) {
return new JiraRESTClient(DEFAULT_SEARCH_URL, username, password)
}
private JiraRESTClient(String url, String username, String password) {
super(url)
assert username
assert password
log.debug "Created for user=${username}, url=" + url
this.username = username;
this.password = password;
credentials['os_username'] = this.username
credentials['os_password'] = this.password
}
def get(String path, def query) {
try {
def response = get(path: path, contentType: "application/json", query: query)
assert response.status == 200
assert (response.data instanceof net.sf.json.JSON)
return response
} catch (groovyx.net.http.HttpResponseException e) {
if (e.response.status == 400) {
// HTTP 400: Bad Request, JIRA returned error
throw new IllegalArgumentException("JIRA query failed, response data=${e.response.data}", e)
} else {
throw new IOException("JIRA connection failed, got HTTP status ${e.response.status}, response data=${e.response.data}", e)
}
}
}
def post(String path, def body, def query) {
try {
def response = post(path: path, contentType: "application/json", body: body, query: query)
return response
} catch (groovyx.net.http.HttpResponseException e) {
if (e.response.status == 400) {
// HTTP 400: Bad Request, JIRA returned error
throw new IllegalArgumentException("JIRA query failed, got HTTP status 400, response data=${e.response.data}", e)
} else {
throw new IOException("JIRA connection failed, got HTTP status ${e.response.status}, response data=${e.response.data}", e)
}
}
}
/**
* Search JIRA with provided JQL e.g. "project = XXX AND ..."
* @returns response
* @throws IllegalArgumentException in case of bad JQL query
* @throws IOException in case of JIRA connection failure
* @see JiraQueryBuilder to create these JQL queries
*/
def search(String jql) {
assert jql
def query = [:]
query << credentials
query['jql'] = jql
query['startAt'] = 0
query['maxResults'] = 1000
log.debug "Searching with JQL: " + jql
return get("search", query)
}
Credentials are appended in plain sight to the url, but for internal use I found this acceptable. The search() gets a JQL string passed, appends the credentials and delegates to our own get() which actually performs groovyx.net.http.RESTClient‘s get() to make it happen.
Querying Release Notes
The query to get all Resolved or Closed issues for a certain fix version can be encapsulated in a getReleaseNotes method, such as seen below.
def getReleaseNotes(String fixVersion) {
String jql = new JiraQueryBuilder(DEFAULT_PROJECT)
.withStatus(RESOLVED, CLOSED)
.withFixVersion(fixVersion)
.build()
return search(jql)
}
Done
I’m still kickstarting this script with e.g. the gmaven-plugin which allows me to get my JIRA credentials from e.g. settings.xml, while the fix version for the JIRA query can be supplied as a property on the command-line.
