Get hands-on training for JIRA Software, Confluence, and more at Atlassian Summit Europe. Register now ›

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

Create the custom field

See here for specifics. Your atlassian-plugin.xml should end up looking something like this:
[cc lang=”xml”] 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”>

${project.description}
${project.version}

A field for referencing issues from another JIRA server.

[/cc]

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:

[cc lang=”xml”][/cc]

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.

[cc lang=”java”]
public class ExternalIssueField extends StringCFType
{
private final EntityLinkService entityLinkService;

public ExternalIssueField(final CustomFieldValuePersister customFieldValuePersister, final GenericConfigManager genericConfigManager, final EntityLinkService entityLinkService)
{
super(customFieldValuePersister, genericConfigManager);
this.entityLinkService = entityLinkService;
}
}[/cc]

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.

[cc lang=”java”]@Override
public Map getVelocityParameters(final Issue issue, final CustomField field, final FieldLayoutItem fieldLayoutItem)
{
final Map result = super.getVelocityParameters(issue, field, fieldLayoutItem);

final EntityLink link = entityLinkService.getPrimaryEntityLink(issue.getProjectObject(), JiraProjectEntityType.class);
final boolean hasLink = 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());
}
return result;
}[/cc]

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:

[cc lang=”java”]#if ($value)
#if (${displayParameters.excel_view})
$textutils.br($textutils.htmlEncode($!value.toString(), false))
#else
#if ($hasLink == true)
$!value.toString()
#else
$!value.toString()
#end
#end
#end[/cc]

This creates a hyperlink to the JIRA issue on the external server.

edit-external-issue.vm:

[cc lang=”java”]#customControlHeader ($action $customField.id $customField.name $fieldLayoutItem.required $displayParameters $auiparams)
#if ($hasLink == false)

No link to another JIRA server!

#else

Enter an issue key for $linkName:

#end
#customControlFooter ($action $customField.id $fieldLayoutItem.fieldDescription $displayParameters $auiparams)[/cc]

This creates a hyperlink to the JIRA project on the external server.

xml-external-issue.vm:

[cc lang=”java”]#if($renderedValue)
$xmlutils.escape($renderedValue)
#elseif ($value)

#end[/cc]

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:

external-issue-1.png

Enter a name and description:

external-issue-2.png

Decide which screens to make the field visible:

external-issue-3.png

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.

external-issue-4.png

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.

external-issue-5.png

There you have it folks! There are plenty of ways to improve this simple example, such as UI validation or auto-completion.

Enhanced by Zemanta

Fresh ideas, announcements, and inspiration for your team, delivered weekly.

Subscribe now

Fresh ideas, announcements, and inspiration for your team, delivered weekly.

Subscribe now