Working with Custom Field Searchers

We have seen how to write a custom field in one of the previous tutorials. Writing the field is one thing but making it available to one of the JIRA's most powerful functionality, i.e. Search, is another!

So how do we do that? In most cases, you wouldn't need a custom searcher. Instead you can use the built in custom field searchers in JIRA itself. The list includes, but not restricted to, Text Field Searcher, Date Searcher, Number Searcher, User Searcher etc.

The first step of course is to determine what is the kind of Searcher your new field needs. For example, a Select field can easily be searched with Text Searcher or an Exact Text Searcher! A User Picker field can be searched with a User Searcher or a Text Searcher.  You might even want to extend one of these Searchers to add some extra functionality. Some special conditions or hacks you want to introduce! Yeah, you know what I mean!!

Now, we have the custom field ready and the Searcher decided. Let us , in this example, consider using a TextSearcher puerly because the customfield we created in the other tutorial is extending a TextCFType.

Here is how JIRA has defined the text searcher for its system custom fields:

<customfield-searcher key="textsearcher" name="Free Text Searcher"
        i18n-name-key="admin.customfield.searcher.textsearcher.name"
        class="com.atlassian.jira.issue.customfields.searchers.TextSearcher">
        <description key="admin.customfield.searcher.textsearcher.desc">Search for values using a free text search.</description>

        <resource type="velocity" name="search" location="templates/plugins/fields/edit-searcher/search-basictext.vm"/>
        <resource type="velocity" name="view" location="templates/plugins/fields/view-searcher/view-searcher-basictext.vm"/>
        <valid-customfield-type package="com.atlassian.jira.plugin.system.customfieldtypes" key="textfield"/>
        <valid-customfield-type package="com.atlassian.jira.plugin.system.customfieldtypes" key="textarea"/>
        <valid-customfield-type package="com.atlassian.jira.plugin.system.customfieldtypes" key="readonlyfield"/>
</customfield-searcher>

We are going to do the same thing in our Atlassian-plugin.xml for our custom field. It will look like this:

<customfield-searcher key="readonly-user-searcher" name="Read Only User Searcher"
        class="com.atlassian.jira.issue.customfields.searchers.TextSearcher">
        <description key="admin.customfield.searcher.textsearcher.desc">Search for Read Only User using a free text search.</description>

        <resource type="velocity" name="search" location="templates/plugins/fields/edit-searcher/search-basictext.vm"/>
        <resource type="velocity" name="view" location="templates/plugins/fields/view-searcher/view-searcher-basictext.vm"/>
        <valid-customfield-type package="com.jtricks" key="readonly-user"/>
</customfield-searcher>

I am sure you would have noticed the changes made. Just to elaborate a bit, there should be a unique key like for everything else and the class should refer to the Searcher you want to point to. It could be your custom Searcher class as we mentioned before but in this case we have chosen JIRA's TextSearcher. Then you can define your own velocity templates for the Search and view for Edit and View 'views' respectively.

And then comes the most important part where you mention your customfield within the valid-customfield-type tag. There can be multiple entries for different custom fields as you saw in the first snippet from Atlassian. In our case we have the read-only user custom field added.

There is basic but very common error you might make here. The package attribute here refers to the atlassian-plugin key where the custom field resides in and not the Java package where the Searcher class resides in! Just to make it clear, the Atlassian plugin key is the key in the first line of your atlassian-plugin.xml which is 'com.jtricks' in our case.

<atlassian-plugin key="com.jtricks" name="J-Tricks Customfields Plugin"  plugins-version="2">

This package (plugin key) along with the customfield key (readonly-user in this case) will point to the right custom field. This would also mean that you can have the same 'readonly-user' in another plugin with a different plugin key!

Now all these works fine pre 4.x or pre OSGI! With the introduction of v2 plugins, courtesy OSGI bundles, referring the JIRA classes directly in the atlassian-plugin.xml will fail sometimes because it can't resolve all the dependencies (the notorious Unsatisfied dependency errors!). This is because some of the classes are not available for dependency injection in the version 2 plugins as they were in version 1 plugins.

But don't worry, there is an easy hack to do it. Just create a dummy custom Searcher class with the constructor that does the dependency injection for you.  So you will endup doing something what Leonids suggest in the forums:

public class MySearcher extends SomeJiraSearcher {
   public MySearcher(PluginComponent ioc) {
      super(ioc, ComponentManager.getInstanceOfType(anotherType));
  }
}

Have a look at this thread and this for more details and a sample for this issue.

If nothing works, you always have the option of adding the field to the system-customfield-types.xml under WEB-INF/classes along with the JIRA system custom fields. i.e. one more valid-customfield-type entry into the relevant customfield-searcher element.

Phew! So we have the searcher defined and the stage is set to create your first filter with the new custom field. Happy coding.