JIRA Plugin Development——Configurable Custom Field Plugin

关于JIRA Plugin开发的中文资料相当少，这可能还是由于JIRA Plugin开发在国内比较小众的原因吧，下面介绍下自己的一个JIRA Plugin开发的详细过程。

业务需求

创建JIRA ISSUE时能提供一个字段，字段内容是类似于订单号或手机号这种样式的数据，并且显示出来是一个链接，点击后可跳转到订单详情页或手机号所对应的客户的整个订单页，供用户查看和此任务工单关联的订单数据；

例如：

订单号为123456；

订单详情URL为：http://192.168.11.211?order=123456；

则字段中显示出来的只能是123456的链接，而不是完整的URL，操作的用户是看不到整个链接地址的，不管是view还是edit界面，都不会显示URL地址，用户只需输入或修改订单号，保存后点击就可以直接跳转到订单详情页面；

解决办法

对于这种需求，JIRA自带的Custom Field Plugin就无法满足了，只能自己开发，开始没想到使用可配置的Custom Field，开始的解决办法是字段Value仍保存完整的URL，只是在显示和编辑时只让用户看到订单号，这样做有几个缺点，具体如下所示：

• 必须在字段配置的Default Value中绑定URL前缀，拿上面的例子来说，就是http://192.168.11.211?order=，但是在显示和编辑时又不能让用户看到，只能在Velocity模板中去做一堆事情来完成，包括和默认URL前缀的匹配，js的处理等，限制性非常大；
• 无法实现根据订单号的搜索，例如在Issue的Search for issues中搜索订单号为123456的issue就无法实现，因为字段值本身还是整个URL，而不是单纯的订单号；

身为程序员，自然不允许自己做出的东西是上面那样的残次品，于是研究了下可配置的Custom Field Plugin的实现过程；

关于Configurable Custom Field Plugin的参考资料相当少，具体实现参考了《Practical JIRA Plugins》第三章的一个例子；

可配置的字段，就是可以为字段添加一个配置项，在配置项中保存URL前缀，Value值只存储订单号，这样可以保证可按订单号搜索相关issue；

具体实现

实现Plugin的前提是我们的环境已经准备好了，即Atlassian的SDK包已经安装成功，并且本机Java环境的配置也已经OK，具体可参考：

https://developer.atlassian.com/docs/getting-started/set-up-the-atlassian-plugin-sdk-and-build-a-project

创建Plugin Project

切换到相应目录下，使用如下命令创建JIRA Plugin：

$ atlas-create-jira-plugin

会提示输入group-id，artifact-id，version，package，具体如下：

group-id	com.mt.mcs.customfields
artifact-id	configurableURL
version	1.0-SNAPSHOT
package	com.mt.mcs.customfields.configurableurl

 

 

 

 

 

 

group-id和artifact-id用来生成Plugin的唯一key，在本例中此Plugin的key为：com.mt.mcs.customfields.configurableurl；

version用在pom.xml中，并且是生成的.jar文件名种的一部分；

package是编写源码使用的Java包名；

之后会出现提示是否确认构建此Plugin，输入"Y"或"y"即可；

将项目导入IDE

我是用的是idea，操作很简单，只需Import Project—>当前Plugin的根目录（即pom.xml文件所在的目录），点击pom.xml后，点击导入，一路next即可（选择Java环境时记得选择你配置好的Java版本），具体可参考：https://developer.atlassian.com/docs/developer-tools/working-in-an-ide/configure-idea-to-use-the-sdk；

如果使用Eclipse，可参考：https://developer.atlassian.com/docs/getting-started/set-up-the-atlassian-plugin-sdk-and-build-a-project/set-up-the-eclipse-ide-for-linux；

修改pom.xml

添加你的组织或公司名称以及你网址的URL到<organization>，具体如下所示：

<organization>

    <name>Example Company</name>

    <url>http://www.example.com/</url>

</organization>

　　修改<description>元素；

<description>This plugin is used for an URL which can config prefix.</description>

　　添加customfield-type到atlassian-plugin.xml

添加完成后的atlassian-plugin.xml如下所示：

 1 <atlassian-plugin key="${project.groupId}.${project.artifactId}" name="${project.name}" plugins-version="2">

 2     <plugin-info>

 3         <description>${project.description}</description>

 4         <version>${project.version}</version>

 5         <vendor name="${project.organization.name}" url="${project.organization.url}" />

 6         <param name="plugin-icon">images/pluginIcon.png</param>

 7         <param name="plugin-logo">images/pluginLogo.png</param>

 8     </plugin-info>

 9 

10     <!-- add our i18n resource -->

11     <resource type="i18n" name="i18n" location="configurableURL"/>

12 

13     <!-- import from the product container -->

14     <component-import key="applicationProperties" interface="com.atlassian.sal.api.ApplicationProperties" />

15 

16     <customfield-type key="configurable-url"

17                       name="Configurable URL"

18                       class="com.mt.mcs.customfields.configurableurl.PrefixUrlCFType">

19         <description>

20             The Prefix URL Custom Field Type Plugin ...

21         </description>

22         <resource type="velocity"

23                   name="view"

24                   location="templates/com/mt/mcs/customfields/configurableurl/view.vm"></resource>

25         <resource type="velocity"

26                   name="edit"

27                   location="templates/com/mt/mcs/customfields/configurableurl/edit.vm"></resource>

28     </customfield-type>

29 </atlassian-plugin>

 

　　第一行key="${project.groupId}.${project.artifactId}"，表示此plugin的唯一标识；

　　<customfield-type key="configurable-url" ...中的key为此customfield-type的唯一标识，要求在atlassian-plugin.xml中是唯一的；

name="Configurable URL"，name为此custom field type在JIRA中显示的名字；

class="com.meituan.mcs.customfields.configurableurl.PrefixUrlCFType">，class为实现custom field type的Java类；

resource元素中包含了view和edit时，此字段使用的Velocity模板引擎；

创建CustomField Type的Class

现在我们需要创建一个Java类，实现CustomFieldType接口，并实现新的custom field type的各项功能，在类名末尾附加"CFType"是一个通用的约定，例如在我们的例子中，使用的Java类名为PrefixUrlCFType.java；

 代码如下所示：

 1 package com.mt.mcs.customfields.configurableurl;

 2 

 7 import com.atlassian.jira.issue.Issue;

 8 import com.atlassian.jira.issue.customfields.impl.FieldValidationException;

 9 import com.atlassian.jira.issue.customfields.impl.GenericTextCFType;

10 import com.atlassian.jira.issue.customfields.manager.GenericConfigManager;

11 import com.atlassian.jira.issue.customfields.persistence.CustomFieldValuePersister;

12 import com.atlassian.jira.issue.fields.CustomField;

13 import com.atlassian.jira.issue.fields.config.FieldConfig;

14 import com.atlassian.jira.issue.fields.config.FieldConfigItemType;

15 import com.atlassian.jira.issue.fields.layout.field.FieldLayoutItem;

16 

17 import java.util.List;

18 import java.util.Map;

19 import java.util.regex.Matcher;

20 import java.util.regex.Pattern;

21 

22 public class PrefixUrlCFType extends GenericTextCFType {

23 

24     public PrefixUrlCFType(CustomFieldValuePersister customFieldValuePersister, GenericConfigManager genericConfigManager) {

25         super(customFieldValuePersister, genericConfigManager);

26     }

27 

28     @Override

29     public List<FieldConfigItemType> getConfigurationItemTypes() {

30         final List<FieldConfigItemType> configurationItemTypes = super.getConfigurationItemTypes();

31         configurationItemTypes.add(new PrefixURLConfigItem());

32         return configurationItemTypes;

33     }

34 

35     @Override

36     public Map<String, Object> getVelocityParameters(final Issue issue,

37                                                      final CustomField field,

38                                                      final FieldLayoutItem fieldLayoutItem) {

39         final Map<String, Object> map = super.getVelocityParameters(issue, field, fieldLayoutItem);

40 

41         // This method is also called to get the default value, in

42         // which case issue is null so we can't use it to add currencyLocale

43         if (issue == null) {

44             return map;

45         }

46 

47         FieldConfig fieldConfig = field.getRelevantConfig(issue);

48         //add what you need to the map here50 

51         return map;

52     }

53 

54     public String getSingularObjectFromString(final String string) throws FieldValidationException

55     {

56         // JRA-14998 - trim the value.

57         final String value = (string == null) ? "Default" : string.trim();

58         if (value != null && value != "Default") {

59             Pattern p = Pattern.compile("^[0-9A-Za-z]+$");

60             Matcher m = p.matcher(value);

61             if (!m.matches()) {

62                 throw new FieldValidationException("Not Valid, only support a-z, A-Z and 0-9 ...");

63             }

64         }

65         return value;

66     }

67 }

添加配置项到Custom Field

对于每一个custom field，JIRA允许配置不同的内容，例如在不同的项目和任务类型中，select list字段就可以配置不同的option；

对于字段的配置项，我们首先要做的就是决定配置项中要存储什么值，在我们的项目中，存储的是URL前缀，使用字符串形式保存即可；

JIRA的配置项需要新定义一个类，并需要实现com.atlassian.jira.issue.fields.config.FieldConfigItemType接口，除此之外，我们还需要在JIRA中定义一个新的web页面，让我们填写并保存配置项的值；

代码如下所示：

 1 package com.meituan.mcs.customfields.configurableurl;

 2 

 3 import com.atlassian.jira.issue.Issue;

 4 import com.atlassian.jira.issue.fields.config.FieldConfig;

 5 import com.atlassian.jira.issue.fields.config.FieldConfigItemType;

 6 import com.atlassian.jira.issue.fields.layout.field.FieldLayoutItem;

 7 

 8 import java.util.HashMap;

 9 import java.util.Map;

10 

14 public class PrefixURLConfigItem implements FieldConfigItemType {

15 

16     @Override

17     //The name of this kind of configuration, as seen in the field configuration scheme;

18     public String getDisplayName() {

19         return "Config Prefix URL";

20     }

21 

22     @Override

23     // This is the text shown in the field configuration screen;

24     public String getDisplayNameKey() {

25         return "Prefix Of The URL";

26     }

27 

28     @Override

29     // This is the current value as shown in the field configuration screen

30     public String getViewHtml(FieldConfig fieldConfig, FieldLayoutItem fieldLayoutItem) {

31         String prefix_url = DAO.getCurrentPrefixURL(fieldConfig);

32         return prefix_url;

33     }

34 

35     @Override

36     //The unique identifier for this kind of configuration,

37     //and also the key for the $configs Map used in edit.vm

38     public String getObjectKey() {

39         return "PrefixUrlConfig";

40     }

41 

42     @Override

43     // Return the Object used in the Velocity edit context in $configs

44     public Object getConfigurationObject(Issue issue, FieldConfig fieldConfig) {

45         Map result = new HashMap();

46         result.put("prefixurl", DAO.getCurrentPrefixURL(fieldConfig));

47         return result;

48     }

49 

50     @Override

51     // Where the Edit link should redirect to when it's clicked on

52     public String getBaseEditUrl() {

53         return "EditPrefixUrlConfig.jspa";

54     }

55 }

DAO（Data Access Object）类的任务就是存储配置数据到数据库，具体数据存储先不在这里详细说明了，DAO类代码如下所示：

 1 package com.mt.mcs.customfields.configurableurl;

 2 

 3 import com.atlassian.jira.issue.fields.config.FieldConfig;

 4 import com.opensymphony.module.propertyset.PropertySet;

 5 import com.opensymphony.module.propertyset.PropertySetManager;

 6 import org.apache.log4j.Logger;

 7 

 8 import java.util.HashMap;

 9 

10 public class DAO {

11 

12     public static final Logger log;

13 

14     static {

15         log = Logger.getLogger(DAO.class);

16     }

17 

18     private static PropertySet ofbizPs = null;

19 

20     private static final int ENTITY_ID = 20000;

21 

22     private static PropertySet getPS() {

23         if (ofbizPs == null) {

24             HashMap ofbizArgs = new HashMap();

25             ofbizArgs.put("delegator.name", "default");

26             ofbizArgs.put("entityName", "prefix_url_fields");

27             ofbizArgs.put("entityId", new Long(ENTITY_ID));

28             ofbizPs = PropertySetManager.getInstance("ofbiz", ofbizArgs);

29         }

30         return ofbizPs;

31     }

32 

33     private static String getEntityName(FieldConfig fieldConfig) {

34         Long context = fieldConfig.getId();

35         String psEntityName = fieldConfig.getCustomField().getId() + "_" + context + "_config";

36         return psEntityName;

37     }

38 

39     public static String retrieveStoredValue(FieldConfig fieldConfig) {

40         String entityName = getEntityName(fieldConfig);

41         return getPS().getString(entityName);

42     }

43 

44     public static void updateStoredValue(FieldConfig fieldConfig, String value) {

45         String entityName = getEntityName(fieldConfig);

46         getPS().setString(entityName, value);

47     }

48 

49     public static String getCurrentPrefixURL(FieldConfig fieldConfig) {

50         String prefixurl = retrieveStoredValue(fieldConfig);

51         log.info("Current stored prefix url is " + prefixurl);

52         if (prefixurl == null || prefixurl.equals("")) {

53             prefixurl = null;

54         }

55         return prefixurl;

56     }

57 }

做完这些之后，还需要把PrefixURLConfigItem类和PrefixUrlCFType类关联起来，需要重写getConfigurationItemTypes方法，添加后的PrefixUrlCFType类如下所示：

 1 package com.mt.mcs.customfields.configurableurl;

 2 

 3 import com.atlassian.jira.issue.Issue;

 4 import com.atlassian.jira.issue.customfields.impl.FieldValidationException;

 5 import com.atlassian.jira.issue.customfields.impl.GenericTextCFType;

 6 import com.atlassian.jira.issue.customfields.manager.GenericConfigManager;

 7 import com.atlassian.jira.issue.customfields.persistence.CustomFieldValuePersister;

 8 import com.atlassian.jira.issue.fields.CustomField;

 9 import com.atlassian.jira.issue.fields.config.FieldConfig;

10 import com.atlassian.jira.issue.fields.config.FieldConfigItemType;

11 import com.atlassian.jira.issue.fields.layout.field.FieldLayoutItem;

12 

13 import java.util.List;

14 import java.util.Map;

15 import java.util.regex.Matcher;

16 import java.util.regex.Pattern;

17 

18 public class PrefixUrlCFType extends GenericTextCFType {

19 

20     public PrefixUrlCFType(CustomFieldValuePersister customFieldValuePersister, GenericConfigManager genericConfigManager) {

21         super(customFieldValuePersister, genericConfigManager);

22     }

23 

24     @Override

25     public List<FieldConfigItemType> getConfigurationItemTypes() {

26         final List<FieldConfigItemType> configurationItemTypes = super.getConfigurationItemTypes();

27         configurationItemTypes.add(new PrefixURLConfigItem());

28         return configurationItemTypes;

29     }

30 

31     @Override

32     public Map<String, Object> getVelocityParameters(final Issue issue,

33                                                      final CustomField field,

34                                                      final FieldLayoutItem fieldLayoutItem) {

35         final Map<String, Object> map = super.getVelocityParameters(issue, field, fieldLayoutItem);

36 

37         // This method is also called to get the default value, in

38         // which case issue is null so we can't use it to add currencyLocale

39         if (issue == null) {

40             return map;

41         }

42 

43         FieldConfig fieldConfig = field.getRelevantConfig(issue);

44         //add what you need to the map here

45         map.put("currentPrefixURL", DAO.getCurrentPrefixURL(fieldConfig));

46 

47         return map;

48     }

49 

50     public String getSingularObjectFromString(final String string) throws FieldValidationException

51     {

52         // JRA-14998 - trim the value.

53         final String value = (string == null) ? "Default" : string.trim();

54         if (value != null && value != "Default") {

55             Pattern p = Pattern.compile("^[0-9A-Za-z]+$");

56             Matcher m = p.matcher(value);

57             if (!m.matches()) {

58                 throw new FieldValidationException("Not Valid, only support a-z, A-Z and 0-9 ...");

59             }

60         }

61         return value;

62     }

63 }

 Velocity模板引擎

custom field在JIRA中显示和编辑，需要使用Velocity模板，即view.vm和edit.vm，具体如下所示：

view.vm

 1 #disable_html_escaping()

 2 #set($defaultValue = "Default")

 3 #if ($value && $value != $defaultValue)

 4     #if ($currentPrefixURL)

 5         <a class="tinylink" target="_blank" href="$currentPrefixURL$value">$!textutils.htmlEncode($value)</a>

 6     #else

 7         #set($displayValue = "没有配置URL前缀...")

 8         $!textutils.htmlEncode($displayValue)

 9     #end

10 #elseif ($value == $defaultValue)

11     #set($displayValue = "请输入相关信息...")

12     $textutils.htmlEncode($displayValue)

13 #else

14     #set($displayValue = "出现错误了....")

15     $textutils.htmlEncode($displayValue)

16 #end

edit.vm

 1 #disable_html_escaping()

 2 #customControlHeader ($action $customField.id $customField.name $fieldLayoutItem.required $displayParameters $auiparams)

 3 #set($configObj = $configs.get("PrefixUrlConfig"))

 4 #set($prefixUrl = $configObj.get("prefixurl"))

 5 #set($defaultValue = "Default")

 6 #if ($value == $defaultValue)

 7     <input class="text" id="displayText" name="displayText" type="text" value="" onchange="changeValue(${customField.id})">

 8     <input class="text" id="$customField.id" name="$customField.id" type="hidden" value="$textutils.htmlEncode($!value)">

 9 #else

10     <input class="text" id="$customField.id" name="$customField.id" type="text" value="$textutils.htmlEncode($!value)">

11 #end

12 <script type="text/javascript">

13   function changeValue(cfElmId) {

14     var cfElmId = cfElmId.id;

15     var element = document.getElementById("displayText");

16     var elmVal = element.value;

17     var cfElm = document.getElementById(cfElmId);

18     cfElm.value = elmVal;

19   }

20 </script>

21 #customControlFooter ($action $customField.id $fieldLayoutItem.fieldDescription $displayParameters $auiparams)

WebWork Action

到现在为止，我们定义了一个新类型的配置项，并且更新了PrefixUrlCFType类和Velocity模板引擎，我们还需要一个新的web页面，来设置配置项的值（即URL前缀信息）并保存到数据库；

JIRA是通过WebWork web应用框架来定义web页面的，需要在atlassian-plugin.xml文件中配置webwork元素，具体如下所示：

 1 <webwork1 key="url-configurable"

 2           name="URL configuration action"

 3           class="java.lang.Object">

 4     <description>

 5         The action for editing a prefix url custom field type configuration.

 6     </description>

 7     <actions>

 8         <action name="com.mt.mcs.customfields.configurableurl.EditPrefixUrlConfig"

 9                 alias="EditPrefixUrlConfig">

10             <view name="input">

11                 /templates/com/mt/mcs/customfields/configurableurl/edit-config.vm

12             </view>

13             <view name="securitybreach">

14                 /secure/views/securitybreach.jsp

15             </view>

16         </action>

17     </actions>

18 </webwork1>

使用的edit-config.vm模板文件代码如下所示：

 1 <html>

 2 <head>

 3   <title>

 4       $i18n.getText('common.words.configure')

 5       $action.getCustomField().getName()

 6   </title>

 7   <meta content="admin" name="decorator">

 8   <link rel="stylesheet" type="text/css" media="print" href="/styles/combined-printtable.css">

 9   <link rel="stylesheet" type="text/css" media="all" href="/styles/combined.css">

10   <style>

11     table.base-table {

12       margin: 15px auto;

13       border-spacing: 5px 10px;

14       line-height: 1.5;

15       font-size: 16px;

16     }

17     input.prefixurl {

18       outline: none;

19       box-shadow: bisque;

20       width: 350px !important;

21     }

22     table.base-table input#Save {

23       margin-left: 80px;

24     }

25   </style>

26 </head>

27 <body>

28 <h2 class="formtitle">

29     $i18n.getText('common.words.configure') $action.getCustomField().getName()

30 </h2>

31 <div class="aui-message aui-message-info">

32   <p class="title">

33     <span class="aui-icon icon-info"></span>

34     <strong>Notice</strong>

35   </p>

36   <p>

37     Config the prefix of your URL.

38   </p>

39   <p>

40     At the end of the URL, you need to add a '/', such as 'http://192.168.11.234/' !

41   </p>

42 </div>

43 <form action="EditPrefixUrlConfig.jspa" method="post" class="aui">

44   <table class="base-table">

45     <tr>

46       <td>

47         Prefix Url:&nbsp;

48       </td>

49       <td>

50         #set($prefix_url = $action.getPrefixurl())

51         <input type="text" name="prefixurl" id="prefixurl" value="$!prefix_url" class="text prefixurl">

52       </td>

53     </tr>

54     <tr>

55       <td colspan="2">

56         <input type="submit" name="Save" id="Save" value="$i18n.getText('common.words.save')" class="aui-button">

57         <a href="ConfigureCustomField!default.jspa?customFieldId=$action.getCustomField().getIdAsLong().toString()"

58            id="cancelButton" class="aui-button" name="ViewCustomFields.jspa">

59           Cancel

60         </a>

61       </td>

62     </tr>

63   </table>

64   <input type="hidden" name="fieldConfigId" value="$fieldConfigId">

65 </form>

66 </body>

67 </html>

Action Class

配置项的web页面使用的Action类是EditPrefixUrlConfig.java，代码如下所示：

 1 package com.mt.mcs.customfields.configurableurl;

 2 

 3 import com.atlassian.jira.config.managedconfiguration.ManagedConfigurationItemService;

 4 import com.atlassian.jira.issue.customfields.impl.FieldValidationException;

 5 import com.atlassian.jira.security.Permissions;

 6 import com.atlassian.jira.web.action.admin.customfields.AbstractEditConfigurationItemAction;

 7 import com.opensymphony.util.UrlUtils;

 8 

 9 public class EditPrefixUrlConfig extends AbstractEditConfigurationItemAction {

10 

11     protected EditPrefixUrlConfig(ManagedConfigurationItemService managedConfigurationItemService) {

12         super(managedConfigurationItemService);

13     }

14 

15     private String prefixurl;

16 

17     public void setPrefixurl(String prefixurl) {

18         this.prefixurl = prefixurl;

19     }

20 

21     public String getPrefixurl() {

22         return this.prefixurl;

23     }

24 

25     protected void doValidation() {

26         String prefix_url = getPrefixurl();

27         prefix_url = (prefix_url == null) ? null : prefix_url.trim();

28         if (prefix_url == null) {

29             return;

30         }

31         if (!UrlUtils.verifyHierachicalURI(prefix_url)) {

32             addErrorMessage("ERROR: " + prefix_url + " is not a valid URL...");

33         }

34     }

35 

36     protected String doExecute() throws Exception {

37         if (!isHasPermission(Permissions.ADMINISTER)) {

38             return "securitybreach";

39         }

40         if (getPrefixurl() == null) {

41             setPrefixurl(DAO.retrieveStoredValue(getFieldConfig()));

42         }

43         DAO.updateStoredValue(getFieldConfig(), getPrefixurl());

44         String save = request.getParameter("Save");

45         if (save != null && save.equals("Save")) {

46             setReturnUrl("/secure/admin/ConfigureCustomField!default.jspa?customFieldId=" + getFieldConfig().getCustomField().getIdAsLong().toString());

47             return getRedirect("not used");

48         }

49         return INPUT;

50     }

51 }

这样整个可配置的Custom Field Plugin已经正式开发完成了，只是搜索功能还没有实现，搜索只是继承已有的Searcher即可，本例继承的是TextSearcher；

Searcher的实现可参考：https://www.safaribooksonline.com/library/view/practical-jira-plugins/9781449311322/ch04.html，讲解非常详细；