JIRA Plugin Development——Configurable Custom Field Plugin

时间：2021-10-04 00:06:32

关于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如下所示：

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

     <plugin-info>

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

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

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

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

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

     </plugin-info>

     <!-- add our i18n resource -->

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

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

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

     <customfield-type key="configurable-url"

                       name="Configurable URL"

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

         <description>

             The Prefix URL Custom Field Type Plugin ...

         </description>

         <resource type="velocity"

                   name="view"

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

         <resource type="velocity"

                   name="edit"

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

     </customfield-type>

 </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；

代码如下所示：

 package com.mt.mcs.customfields.configurableurl;

 import com.atlassian.jira.issue.Issue;

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

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

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

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

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

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

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

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

 import java.util.List;

 import java.util.Map;

 import java.util.regex.Matcher;

 import java.util.regex.Pattern;

 public class PrefixUrlCFType extends GenericTextCFType {

     public PrefixUrlCFType(CustomFieldValuePersister customFieldValuePersister, GenericConfigManager genericConfigManager) {

         super(customFieldValuePersister, genericConfigManager);

     }

     @Override

     public List<FieldConfigItemType> getConfigurationItemTypes() {

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

         configurationItemTypes.add(new PrefixURLConfigItem());

         return configurationItemTypes;

     }

     @Override

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

                                                      final CustomField field,

                                                      final FieldLayoutItem fieldLayoutItem) {

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

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

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

         if (issue == null) {

             return map;

         }

         FieldConfig fieldConfig = field.getRelevantConfig(issue);

         //add what you need to the map here

         return map;

     }

     public String getSingularObjectFromString(final String string) throws FieldValidationException

     {

         // JRA-14998 - trim the value.

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

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

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

             Matcher m = p.matcher(value);

             if (!m.matches()) {

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

             }

         }

         return value;

     }

 }

添加配置项到Custom Field

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

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

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

代码如下所示：

 package com.meituan.mcs.customfields.configurableurl;

 import com.atlassian.jira.issue.Issue;

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

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

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

 import java.util.HashMap;

 import java.util.Map;

 public class PrefixURLConfigItem implements FieldConfigItemType {

     @Override

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

     public String getDisplayName() {

         return "Config Prefix URL";

     }

     @Override

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

     public String getDisplayNameKey() {

         return "Prefix Of The URL";

     }

     @Override

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

     public String getViewHtml(FieldConfig fieldConfig, FieldLayoutItem fieldLayoutItem) {

         String prefix_url = DAO.getCurrentPrefixURL(fieldConfig);

         return prefix_url;

     }

     @Override

     //The unique identifier for this kind of configuration,

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

     public String getObjectKey() {

         return "PrefixUrlConfig";

     }

     @Override

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

     public Object getConfigurationObject(Issue issue, FieldConfig fieldConfig) {

         Map result = new HashMap();

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

         return result;

     }

     @Override

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

     public String getBaseEditUrl() {

         return "EditPrefixUrlConfig.jspa";

     }

 }

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

 package com.mt.mcs.customfields.configurableurl;

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

 import com.opensymphony.module.propertyset.PropertySet;

 import com.opensymphony.module.propertyset.PropertySetManager;

 import org.apache.log4j.Logger;

 import java.util.HashMap;

 public class DAO {

     public static final Logger log;

     static {

         log = Logger.getLogger(DAO.class);

     }

     private static PropertySet ofbizPs = null;

     private static final int ENTITY_ID = 20000;

     private static PropertySet getPS() {

         if (ofbizPs == null) {

             HashMap ofbizArgs = new HashMap();

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

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

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

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

         }

         return ofbizPs;

     }

     private static String getEntityName(FieldConfig fieldConfig) {

         Long context = fieldConfig.getId();

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

         return psEntityName;

     }

     public static String retrieveStoredValue(FieldConfig fieldConfig) {

         String entityName = getEntityName(fieldConfig);

         return getPS().getString(entityName);

     }

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

         String entityName = getEntityName(fieldConfig);

         getPS().setString(entityName, value);

     }

     public static String getCurrentPrefixURL(FieldConfig fieldConfig) {

         String prefixurl = retrieveStoredValue(fieldConfig);

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

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

             prefixurl = null;

         }

         return prefixurl;

     }

 }

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

 package com.mt.mcs.customfields.configurableurl;

 import com.atlassian.jira.issue.Issue;

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

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

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

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

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

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

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

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

 import java.util.List;

 import java.util.Map;

 import java.util.regex.Matcher;

 import java.util.regex.Pattern;

 public class PrefixUrlCFType extends GenericTextCFType {

     public PrefixUrlCFType(CustomFieldValuePersister customFieldValuePersister, GenericConfigManager genericConfigManager) {

         super(customFieldValuePersister, genericConfigManager);

     }

     @Override

     public List<FieldConfigItemType> getConfigurationItemTypes() {

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

         configurationItemTypes.add(new PrefixURLConfigItem());

         return configurationItemTypes;

     }

     @Override

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

                                                      final CustomField field,

                                                      final FieldLayoutItem fieldLayoutItem) {

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

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

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

         if (issue == null) {

             return map;

         }

         FieldConfig fieldConfig = field.getRelevantConfig(issue);

         //add what you need to the map here

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

         return map;

     }

     public String getSingularObjectFromString(final String string) throws FieldValidationException

     {

         // JRA-14998 - trim the value.

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

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

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

             Matcher m = p.matcher(value);

             if (!m.matches()) {

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

             }

         }

         return value;

     }

 }

Velocity模板引擎

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

view.vm

 #disable_html_escaping()

 #set($defaultValue = "Default")

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

     #if ($currentPrefixURL)

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

     #else

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

         $!textutils.htmlEncode($displayValue)

     #end

 #elseif ($value == $defaultValue)

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

     $textutils.htmlEncode($displayValue)

 #else

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

     $textutils.htmlEncode($displayValue)

 #end

edit.vm

 #disable_html_escaping()

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

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

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

 #set($defaultValue = "Default")

 #if ($value == $defaultValue)

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

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

 #else

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

 #end

 <script type="text/javascript">

   function changeValue(cfElmId) {

     var cfElmId = cfElmId.id;

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

     var elmVal = element.value;

     var cfElm = document.getElementById(cfElmId);

     cfElm.value = elmVal;

   }

 </script>

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

WebWork Action

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

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

 <webwork1 key="url-configurable"

           name="URL configuration action"

           class="java.lang.Object">

     <description>

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

     </description>

     <actions>

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

                 alias="EditPrefixUrlConfig">

             <view name="input">

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

             </view>

             <view name="securitybreach">

                 /secure/views/securitybreach.jsp

             </view>

         </action>

     </actions>

 </webwork1>

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

 <html>

 <head>

   <title>

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

       $action.getCustomField().getName()

   </title>

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

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

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

   <style>

     table.base-table {

       margin: 15px auto;

       border-spacing: 5px 10px;

       line-height: 1.5;

       font-size: 16px;

     }

     input.prefixurl {

       outline: none;

       box-shadow: bisque;

       width: 350px !important;

     }

     table.base-table input#Save {

       margin-left: 80px;

     }

   </style>

 </head>

 <body>

 <h2 class="formtitle">

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

 </h2>

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

   <p class="title">

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

     <strong>Notice</strong>

   </p>

   <p>

     Config the prefix of your URL.

   </p>

   <p>

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

   </p>

 </div>

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

   <table class="base-table">

     <tr>

       <td>

         Prefix Url:&nbsp;

       </td>

       <td>

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

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

       </td>

     </tr>

     <tr>

       <td colspan="2">

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

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

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

           Cancel

         </a>

       </td>

     </tr>

   </table>

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

 </form>

 </body>

 </html>

Action Class

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

 package com.mt.mcs.customfields.configurableurl;

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

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

 import com.atlassian.jira.security.Permissions;

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

 import com.opensymphony.util.UrlUtils;

 public class EditPrefixUrlConfig extends AbstractEditConfigurationItemAction {

     protected EditPrefixUrlConfig(ManagedConfigurationItemService managedConfigurationItemService) {

         super(managedConfigurationItemService);

     }

     private String prefixurl;

     public void setPrefixurl(String prefixurl) {

         this.prefixurl = prefixurl;

     }

     public String getPrefixurl() {

         return this.prefixurl;

     }

     protected void doValidation() {

         String prefix_url = getPrefixurl();

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

         if (prefix_url == null) {

             return;

         }

         if (!UrlUtils.verifyHierachicalURI(prefix_url)) {

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

         }

     }

     protected String doExecute() throws Exception {

         if (!isHasPermission(Permissions.ADMINISTER)) {

             return "securitybreach";

         }

         if (getPrefixurl() == null) {

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

         }

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

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

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

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

             return getRedirect("not used");

         }

         return INPUT;

     }

 }

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

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

相关文章