A Simple JIRA Plugin Using UAL
Monday, 27 June 2011 08:13
I'm going to show you how to create a simple Atlassian Plugin, using the Application Links API. The plugin will be a JIRA Custom Field.
Prerequisites
- Get the Atlassian Plugin SDK.
- Create a skeleton JIRA plugin. I called mine jira-external-issue-plugin.
- Set up your IDE.
Create the custom field
See here for specifics. Your atlassian-plugin.xml should end up looking something like this:
<atlassian-plugin key="${project.groupId}.${project.artifactId}" name="${project.name}" plugins-version="2" xmlns="http://www.atlassian.com/schema/plugins" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.atlassian.com/schema/plugins http://schema.atlassian.com/jira/jira-4.3.xsd"> <plugin-info> <description>${project.description}</description> <version>${project.version}</version> <vendor name="${project.organization.name}" url="${project.organization.url}" /> </plugin-info> <customfield-type key="jira-external-issue-plugin" name="External Issue Field" class="com.mycompany.ExternalIssueField"> <description>A field forreferencing issues from another JIRA server.</description> <resource type="velocity" name="view" location="templates/plugins/fields/view/view-external-issue.vm"/> <resource type="velocity" name="edit" location="templates/plugins/fields/edit/edit-external-issue.vm"/> <resource type="velocity" name="xml" location="templates/plugins/fields/xml/xml-external-issue.vm"/> </customfield-type></atlassian-plugin> |
Component import
We need to get a reference to the API services, so that we can invoke them. I'm going to use the EntityLinkService, to link to projects on other JIRA servers. Add the following to atlassian-plugin.xml:
<component-importkey="entityLinkService" interface="com.atlassian.applinks.api.EntityLinkService"/> |
If you want to learn more about Component Import plugin modules, see here.
The code
The external issue field is basically a text field, so I can reuse some functionality by extending the StringCFType class. Since we have the component import of the EntityLinkService, it will get automatically injected if we have it as a constructor parameter.
publicclassExternalIssueField extendsStringCFType{ privatefinalEntityLinkService entityLinkService; publicExternalIssueField(finalCustomFieldValuePersister customFieldValuePersister, finalGenericConfigManager genericConfigManager, finalEntityLinkService entityLinkService) { super(customFieldValuePersister, genericConfigManager); this.entityLinkService = entityLinkService; }} |
Now we can use the EntityLinkService to pass information to the UI. Overriding the getVelocityParameters() method allows us to pass values to the velocity macros for viewing and editing the field.
@Override publicMap<String, Object> getVelocityParameters(finalIssue issue, finalCustomField field, finalFieldLayoutItem fieldLayoutItem) { finalMap<String, Object> result = super.getVelocityParameters(issue, field, fieldLayoutItem); finalEntityLink link = entityLinkService.getPrimaryEntityLink(issue.getProjectObject(), JiraProjectEntityType.class); finalbooleanhasLink = link != null result.put("hasLink", hasLink); if(hasLink) { result.put("linkName", link.getName()); result.put("projectLinkUrl", link.getDisplayUrl()); result.put("appLinkUrl", link.getApplicationLink().getDisplayUrl()); result.put("linkedProjectKey", link.getKey()); } returnresult; } |
The velocity macros
For the view, edit and xml macros, I used the basic text macros from the JIRA codebase as a starting point.
view-external-issue.vm:
#if($value) #if(${displayParameters.excel_view}) $textutils.br($textutils.htmlEncode($!value.toString(), false)) #else #if($hasLink == true) <a href="/$appLinkUrl/browse/$!value.toString()">$!value.toString()</a> #else $!value.toString() #end #end#end |
This creates a hyperlink to the JIRA issue on the external server.
edit-external-issue.vm:
#customControlHeader ($action $customField.id $customField.name $fieldLayoutItem.required $displayParameters $auiparams) #if($hasLink == false) <div class="field-group">No link to another JIRA server!</div><input hidden="true" id="$customField.id" name="$customField.id" type="text" value="" /> #else <div>Enter an issue key for<a href="/$projectLinkUrl">$linkName</a>: <input class="text" id="$customField.id" name="$customField.id" type="text" value="$textutils.htmlEncode($!value)" /> </div> #end#customControlFooter ($action $customField.id $fieldLayoutItem.fieldDescription $displayParameters $auiparams) |
This creates a hyperlink to the JIRA project on the external server.
xml-external-issue.vm:
#if($renderedValue)<customfieldvalue>$xmlutils.escape($renderedValue)</customfieldvalue>#elseif ($value)<customfieldvalue><![CDATA[$xmlutils.escapeForCdata($value.toString())]]></customfieldvalue>#end |
This is unchanged from xml-basictext.vm.
How to use the plugin
First, there needs to be an Application Link to another JIRA server, and a Project Link to a project on the linked JIRA server. See here for details.
Next, we want to add a custom field, so that we can see the fruits of our work. Select the field type that we created in the plugin:
Enter a name and description:
Decide which screens to make the field visible:
Now we are going to create a new issue, and the external issue field will be there. Simply enter the JIRA key for an issue on the external JIRA server. Notice the hyperlink to the linked project.
Once the issue is created, the external issue field is shown when viewing the issue. Notice the hyperlink to the issue on the external server.
There you have it folks! There are plenty of ways to improve this simple example, such as UI validation or auto-completion.
