Creating an Issue Tracker Plugin
Since 4.0, you can add your own test report plugin by using report plugin APIs. Normally, an typical issue tracker plugin contributes below extension points:
- BuildTabContribution displays a tab in build page to show related issues
- BuildSummaryContribution displays a summary section to show how many issues are related in a build in build dropdown
- Gadget displays the related issues of a configuration in Dashboard page
- CommentTransformer hyperlink the issues occurred in commit comment by a pattern
- StatisticsSupport collects issues by build so that we can compare with a specified build
even more, contribute some steps to create/update issues.
You needn't write the plugin from ground up, plugin com.pmease.quickbuild.tracker.core implements and encapsulates most of them already, just follow below instructions to create an issue tracker plugin. If you are not familiar with how to set up your development environment or how to create and test a plugin, please read plugin tutorials and some plugin examples first. Or you may read the Redmine plugin source code directly. Below we will show you how to add a Redmine plugin.
Plugin Activator
Every issue tracker plugin needs a plugin activator. As plugin com.pmease.quickbuild.tracker.core has already done a lot of things, add it to plugin dependencies in MANIFEST.MF, and actually, in most cases, you only need this dependency.
And then, implement the activator by extending AbstractTrackerPlugin:
public class RedminePlugin extends AbstractTrackerPlugin {
public IssueTracker createTracker() {
return new RedmineTracker();
}
protected IssueCategory createCategory() {
return new RedmineCategory();
}
public Class<?> getConfigurationSettingClass() {
return RedmineSetting.class;
}
}
It is fairly simple, and we will discuss more detailed below.
IssueTracker
IssueTracker is an interface which tell QuickBuild how to fetch issue related information from remote server:
public interface IssueTracker extends CommentTransformer {
/**
* Return the total issues in a build
*/
int getIssueCount(Build build);
/**
* Get the issue pattern which will be used to match issue key in commit message
* @return
*/
Pattern getIssuePattern();
/**
* Extract the issue key from a matched issue key, for example: extract bug:123 to 123, #456 to 456
*
* @param matched
* @return
*/
String extractIssueKey(String matched);
/**
* Batch fetching issues data from remote.
*
* @param keys need be fetched
* @return a map of fetched issues data
*/
Map<String, Issue> fetchIssues(Collection<String> keys);
/**
* Get the issue url pattern which will be used to hyperlink the issue key, for example, for JIRA issue,
* the pattern would be: http://jira-server/browse/$KEY.
* Note: always use <b>$KEY</b> as we will use it to replace with the actual issue key.
*
* The server url can be retrieved from the tracker setting. So, for JIRA, this function can be
* simply implemented like below:
* <code>
* public String getIssueUrlPattern() {
* JiraSetting setting = JiraSetting.get(); // Retrieve JIRA setting of current configuration
* return StringHelper.normalizeUrl(setting.getHost()) + "/browse/$KEY";
* }
* </code>
*
* @return the pattern of issue url
*/
String getIssueUrlPattern();
}
To implement IssueTracker, extend com.pmease.quickbuild.plugin.tracker.core.AbstractIssueTracker which implements most of the functions above:
public class RedmineTracker extends AbstractIssueTracker {
public Map<String, Issue> fetchIssues(Collection<String> keys) {
... ...
}
public String getIssueUrlPattern() {
RedmineSetting setting = RedmineSetting.get();
return StringHelper.normalizeUrl(setting.getHost()) + "/issues/$KEY";
}
@Override
public String extractIssueKey(final String matched) {
Long id = TrackerHelper.extractLong(matched);
if (id == null) {
return null;
} else {
return id.toString();
}
}
}
fetchIssues() is tracker related, you need implement according to your issue tracker API.
Class Issue includes below properties:
public class Issue implements Serializable {
private String issueKey;
private String issueType;
private String summary;
private String status;
private String priority;
private String resolution;
private Calendar created;
private Calendar updated;
private String assignee;
private String reporter;
}
IssueCategory
All issues report will be saved to your configuration or build reports directory. The IssueCategory encapsulates the issue related operations, like save/load from H2 database, displays to user, etc. So implement your IssueCategory like below:
public class RedmineCategory extends IssueCategory {
// return the name of the category
public String getName() {
return "Redmine";
}
// return the unique id of category
public String getId() {
return "redmine";
}
// return the order which you want to display in QuickBuild
public int getOrder() {
return 150;
}
}
Configuration Setting
You need add a configuration setting class let user define the issue tracker server:
@Editable(name = "Redmine Server", order=1000, category="Issue Tracker")
public class RedmineSetting extends AbstractTrackerSetting {
public RedmineSetting() {
// default issue pattern
issuePattern = "(?<!\\:)(?:#|bug:)\\d+";
}
}
AbstractTrackerSetting defines below properties:
public abstract class AbstractTrackerSetting implements TrackerSetting {
String host;
String user;
String password;
String issuePattern;
}
Just add as more fields as you need to the setting class, and apply some annotations to your getter method, QuickBuild will display the form without writing one line for GUI. See this page for details. For example, we add associate project to RedmineSetting:
public class RedmineSetting extends AbstractTrackerSetting {
private String associatedProject;
... ...
@Editable(name = "Associated Project", order = 500)
@NotEmpty
@Scriptable
public String getAssociatedProject() {
return associatedProject;
}
}
Now, in Redmine setting, a new field Associated Project is added which is a required field and also user can use script to provide this property.
Finally, package the plugin and copy to QuickBuild server plugins directory, restart QuickBuild. To test your plugin, here is Redmine, you need:
- configure the Redmine Server in configuration settings
- add a repository to the configuration
- add a checkout step
- trigger a build
- submit some modifications to your repository, in the commit message, add some issues you want
- trigger a build again
If you are lucky, you can find all issues mentioned in commit messages are hyperlinked and a tab named Redmine which displays all issues mentioned in commit messages is added in build page.
Exposing Issues Report
You can also expose your issues report via REST:
@Path("/redmine")
public class RedmineRestResource extends TrackerResource {
}
and then add this class to the plugin activator so QuickBuild can know you want to expose it:
public class RedminePlugin extends AbstractTrackerPlugin {
... ...
protected Class<?>[] getRestResourceClasses() {
return new Class[] { RedmineRestResource.class };
}
And now you can visit below URL to access your issues report:
http://your-quickbuild/rest/redmine
See Interact with Issues for all RESTful functions.
Contributing to Dashboard
If you want to display your issues report to Dashboard, you can create a Gadget class:
@Editable(name = "Redmine Issues", category = GadgetCategory.CHANGES_AND_ISSUES)
public class RedmineGadget extends AbstractIssueGadget {
}
and then add to your plugin activator like:
public class RedminePlugin extends AbstractTrackerPlugin {
... ...
protected Class<? extends Gadget>[] getGadgetClasses() {
return new Class[] { RedmineGadget.class };
}
Now, in Dashboard page, you can find a gadget named Redmine Issues is available. When add it to your dashboard, you may see the gadget like below:
Create/Update Issue
If you want to create/update issues, you can add some step class to do this, and add them to your plugin activator like below:
public class RedminePlugin extends AbstractTrackerPlugin {
... ...
protected Object[] getExtraExtensions() {
return new Object[] {
new StepProvider() {
public Class<? extends Step> getStepClass() {
return CreateIssueStep.class;
}
},
new StepProvider() {
public Class<? extends Step> getStepClass() {
return UpdateIssueStep.class;
}
}
};
}
}