Support for Server products ended Feb. 15, 2024. Learn what this means for you.

Custom field

Purpose of this module type

The custom field plugin module allows you to add new custom field types and searchers to JIRA.

Custom field types - these define the type of a custom field
Custom field seachers - these define the ways a custom field type can be searched

Custom field type configuration

The root element for the custom field type plugin module is customfield-type. It allows the following attributes and child elements for configuration:

Attributes

Name	Description
class	The class which implements this plugin module. The class you need to provide depends on the module type. For example, Confluence theme, layout and colour-scheme modules can use classes already provided in Confluence. So you can write a theme-plugin without any Java code. But for macro and listener modules you need to write your own implementing class and include it in your plugin. See the plugin framework guide to creating plugin module instances. The Java class of the custom field type module. Classes must implement com.atlassian.jira.issue.customfields.CustomFieldType, but there are several concrete implementations that should address the majority of users' needs, including text fields, text areas, user pickers, etc. See the CustomFieldType javadoc for details.
key	The unique identifier of the plugin module. You refer to this key to use the resource from other contexts in your plugin, such as from the plugin Java code or JavaScript resources. 1 2 `<component-import key="appProps" interface="com.atlassian.sal.api.ApplicationProperties"/>` In the example, `appProps` is the key for this particular module declaration, for `component-import`, in this case. I.e. the identifier of the custom field type module.
i18n-name-key	The localisation key for the human-readable name of the plugin module.
name	The human-readable name of the plugin module. I.e. the human-readable name of the custom field type module. Default: the plugin key.

*class and key attributes are required.

Elements

Name	Description
description	A human-readable description of this custom field type plugin module. May be specified as the value of this element for plain text or with the `key` attribute to use the value of a key from the i18n system.
resource type="velocity"	Velocity templates that implement the custom field views.
valid-searcher	(Since JIRA v5.2) This provides an alternative way to define a relationship between a Custom Field Type and a Custom Field Searcher (see also the `valid-customfield-type` element in Custom Field Searcher below). Defines the searchers used for this custom field type. The `package` and `key` attributes together specify the module-complete key under which the custom field searcher is registered. This is most useful for when you have a new Custom Field Type that wants to use an existing searcher from core JIRA or another plugin.

Name

Description

description

A human-readable description of this custom field type plugin module. May be specified as the value of this element for plain text or with the key attribute to use the value of a key from the i18n system.

resource type="velocity"

Velocity templates that implement the custom field views.

valid-searcher

(Since JIRA v5.2)

This provides an alternative way to define a relationship between a Custom Field Type and a Custom Field Searcher (see also the valid-customfield-type element in Custom Field Searcher below).

Defines the searchers used for this custom field type. The package and key attributes together specify the module-complete key under which the custom field searcher is registered.

This is most useful for when you have a new Custom Field Type that wants to use an existing searcher from core JIRA or another plugin.

Example

Here is the custom field JIRA defines for selecting users (taken from system-customfieldtypes-plugin.xml):

1
2
<customfield-type key="userpicker" name="User Picker"
class="com.atlassian.jira.issue.customfields.impl.UserCFType">
   <description>
      Choose a user from the user base via a popup picker window.
   </description>

   <!-- this template is used on the view issue page -->
   <resource type="velocity" name="view"
   location="templates/plugins/fields/view-user.vm" />
   <!-- this template is used on the create/edit issue pages -->
   <resource type="velocity" name="edit"
   location="templates/plugins/fields/edit-userpicker.vm" />
   <!-- this template is used when viewing an issue as XML -->
   <resource type="velocity" name="xml"
   location="templates/plugins/fields/xml-user.vm" />
</customfield-type>

Custom field searcher configuration

The root element for the custom field searcher plugin module is customfield-searcher. It allows the following attributes and child elements for configuration:

Attributes

Name	Description
class	The class which implements this plugin module. The class you need to provide depends on the module type. For example, Confluence theme, layout and colour-scheme modules can use classes already provided in Confluence. So you can write a theme-plugin without any Java code. But for macro and listener modules you need to write your own implementing class and include it in your plugin. See the plugin framework guide to creating plugin module instances. The Java class of the custom field searcher. Classes must implement com.atlassian.jira.issue.customfields.CustomFieldSearcher, but there are several concrete implementations that can handle searching for JIRA's built-in fields. See the CustomFieldSearcher javadoc for more details.
key	The unique identifier of the plugin module. You refer to this key to use the resource from other contexts in your plugin, such as from the plugin Java code or JavaScript resources. 1 2 `<component-import key="appProps" interface="com.atlassian.sal.api.ApplicationProperties"/>` In the example, `appProps` is the key for this particular module declaration, for `component-import`, in this case. I.e. the identifier of the custom field searcher module.
i18n-name-key	The localisation key for the human-readable name of the plugin module.
name	The human-readable name of the plugin module. I.e. the human-readable name of the custom field searcher module. Default: the plugin key.

*class and key attributes are required.

Elements

Name	Description
description	A human-readable description of this custom field searcher plugin module. May be specified as the value of this element for plain text or with the `key` attribute to use the value of a key from the i18n system.
resource type="velocity"	Velocity templates that implement the custom field searcher views.
valid-customfield-type	Defines the custom field types this searcher can apply to. The `package` and `key` attributes together specify the module-complete key under which the custom field is registered; if the searcher is defined in the same `atlassian-plugin.xml` as the type (which is the usual case), then `package` should be the same as the `key` attribute on `<atlassian-plugin>`. Note that since JIRA v5.2 it is also possible to define this relationship in the opposite direction, that is to define searchers that are appropriate for a given custom field type. Strictly speaking this field is no longer mandatory - you need to define the relationship here or in the custom field type configuration. Practically, however, we would normally expect to see a custom field searcher define the applicable custom field types that it knows about. The alternative mechanism is intended for new custom field types defined in other plugins to re-use existing searchers.

Name

Description

description

A human-readable description of this custom field searcher plugin module. May be specified as the value of this element for plain text or with the key attribute to use the value of a key from the i18n system.

resource type="velocity"

Velocity templates that implement the custom field searcher views.

valid-customfield-type

Defines the custom field types this searcher can apply to. The package and key attributes together specify the module-complete key under which the custom field is registered; if the searcher is defined in the same atlassian-plugin.xml as the type (which is the usual case), then package should be the same as the key attribute on <atlassian-plugin>.

Note that since JIRA v5.2 it is also possible to define this relationship in the opposite direction, that is to define searchers that are appropriate for a given custom field type. Strictly speaking this field is no longer mandatory - you need to define the relationship here or in the custom field type configuration. Practically, however, we would normally expect to see a custom field searcher define the applicable custom field types that it knows about. The alternative mechanism is intended for new custom field types defined in other plugins to re-use existing searchers.

*valid-customfield-type element is required.

Example

Here is the custom field searcher JIRA defines for searching users (also taken from system-customfieldtypes-plugin.xml):

1
2
<customfield-searcher key="userpickersearcher" name="User Picker Searcher"
class="com.atlassian.jira.issue.customfields.searchers.UserPickerSearcher">
   <description>
      Allow to search for a user using a userpicker.
   </description>

   <!-- this template is used on the issue navigator search form -->
   <resource type="velocity" name="search"
   location="templates/plugins/fields/search-userpicker.vm" />
   <!-- this element defines the valid custom field types for this searcher -->
   <valid-customfield-type
   package="com.atlassian.jira.plugin.system.customfieldtypes" key="userpicker" />
</customfield-searcher>

Velocity context for custom fields

Below is a list of available objects in the Velocity context for custom fields.

Object	Description
customField	`com.atlassian.jira.issue.fields.CustomField` object. Information on the current field. edit: yes, view: yes, col-view: yes
issue	`com.atlassian.jira.issue.Issue` object. Pretty much everything about the issue. edit: yes, view: yes, col-view: yes
fieldLayoutItem	`com.atlassian.jira.issue.fields.layout.field.FieldLayoutItem`. Is field required? hidden? edit: yes, view: no, col-view: no
action	Calling action. edit: yes, view: no, col-view: no
displayParameters	Custom parameters to the template, such as whether to display headers or not edit: yes, view: no, col-view: no
value	String value of the custom field. Thus this is a String for Date and other single valued fields, List of Strings for Multi selects and CustomFieldParams full of Strings for Cascading selects edit: yes, view: yes, col-view: yes
customFieldParams	This is where the value is pulled from, for convenience edit: yes, view: yes, col-view: yes
config	`com.atlassian.jira.issue.customfields.config.CustomFieldConfig` object. edit: yes, view: no, col-view: no
configs	The various configuration items for that context. This include things like, default values, select list options and other configurable options edit: yes, view: no, col-view: no
i18n	`com.atlassian.jira.web.bean.I18nBean` for your internationalisation needs edit: yes, view: yes, col-view: yes
descriptor	The module descriptor of the current field edit: yes, view: yes, col-view: yes
textutils	`com.opensymphony.util.TextUtils` for text manipulation needs edit: yes, view: yes, col-view: yes
outlookdate	`com.atlassian.jira.web.util.OutlookDate` for formatting dates, JIRA style edit: yes, view: yes, col-view: yes
authcontext	`com.atlassian.jira.security.JiraAuthenticationContext` for authentication information edit: yes, view: yes, col-view: yes
dateutils	`com.atlassian.core.util.DateUtils` more date functions edit: yes, view: yes, col-view: yes
req	`HttpServletRequest` object. edit: yes, view: yes, col-view: yes
baseurl	The `getContextPath` of the req object edit: yes, view: yes, col-view: yes
constantsManager	The `com.atlassian.jira.config.ConstantsManager` object for managing "constants" (issue types, resolutions etc.) edit: yes, view: yes, col-view: yes
projectManager	1 2 `com.atlassian.jira.project.ProjectManager` edit: yes, view: yes, col-view: yes
applicationProperties	`com.atlassian.jira.config.properties.ApplicationProperties` edit: yes, view: yes, col-view: yes
jirautils	`com.atlassian.jira.util.JiraUtils` a random set of methods. has isPublic method edit: yes, view: yes, col-view: yes
jirakeyutils	`com.atlassian.jira.util.JiraKeyUtils` an object used for parsing keys edit: yes, view: yes, col-view: yes
buildutils	`com.atlassian.jira.util.BuildUtils` has information on build numbers, editions etc. edit: yes, view: yes, col-view: yes
velocityhelper	`com.atlassian.jira.util.JiraVelocityHelper` random set of utility methods edit: yes, view: yes, col-view: yes
userutils	`com.atlassian.core.user.UserUtils` untility for getting users edit: yes, view: yes, col-view: yes

+ Other velocity parameters from the custom field type

Adding searching to a custom field

Custom fields need a custom field searcher before you can search them in the Issue Navigator. If a custom field type is a going to behave somewhat like an existing type, then you can reuse an existing searcher. For example, if you're creating a custom field type that's like a multi select list and want to reuse the default multi-select searcher, you could add the block below to your atlassian-plugin.xml (taken from system-customfieldtypes-plugin.xml).

1
2
<customfield-searcher key="multiselectsearcher" name="Multi Select Searcher"
    i18n-name-key="admin.customfield.searcher.multiselectsearcher.name"
    class="com.atlassian.jira.issue.customfields.searchers.MultiSelectSearcher">
    <description key="admin.customfield.searcher.multiselectsearcher.desc">Search for multiple values using a single select list.</description>

    <resource type="velocity" name="search" location="templates/plugins/fields/edit-searcher/search-multiselect.vm"/>
    <resource type="velocity" name="view" location="templates/plugins/fields/view-searcher/view-searcher-multioption.vm"/>
    <resource type="velocity" name="label" location="templates/plugins/fields/view-searcher/label-searcher-basictext.vm"/>
    <valid-customfield-type package="YOUR CUSTOM PACKAGE" key="YOUR CUSTOM FIELD KEY"/>
</customfield-searcher>

which will enable searching for any text based, multi-select custom field type. When creating the custom field, you will now be able to select the multi-select searcher and your custom field should then be displayed in the Issue Navigator.

Note that "YOUR CUSTOM PACKAGE" refers to the package (ie. the module key) of the custom field that the searcher applies to, which is the "key" attribute of the top-level atlassian-plugin element. "YOUR CUSTOM FIELD KEY" refers to the "key" attribute of the customfield element.

Notes

Types and searchers can be combined in different ways to produce new custom fields, for example a "user" custom field could take a simple text searcher (to enter the username as text) or a more complex "user picker searcher" (where the user is picked from a popup window).

For more details, see the Tutorial - Creating a custom field type.
For more information about the atlassian-plugin.xml file, see the Configuring the app descriptor page.
To learn more about the custom field Velocity templates, see Custom field Velocity context unwrapped