Wiki

#JIRA JQL Function Tutorial

This tutorial takes you through the steps involved in creating a JIRA Event Listener.

Make sure you have the Atlassian SDK installed on your system. For information on how to install the Atlassian SDK, refer to

https://developer.atlassian.com/display/DOCS/Install+the+Atlassian+SDK+on+a+Windows+System

###Step 1:

Open a command prompt and in a directory of your choice, do the following

Run the command below:
atlas-create-jira-plugin

Select option 1 for the latest JIRA version supported by your version of the SDK

Enter the following details

group-id: com.stygian.jira.plugins
artifact-id: DateRangeJqlPlugin
version: 1.0.0
package: com.stygian.jira.plugins.jql

atlas-create-jira-plugin

###Step 2:

The SDK would have automatically created an example plugin component. We will first clean up our directories and delete these files that we do not require.

Firstly from your src/main/resources/atlassian-plugin.xml file, remove the following lines. And remember the location from where you are deleting these lines as this is where you will be registering your new plugin module.

<component key="myPluginComponent" class="com.stygian.jira.plugins.listeners.MyPluginComponentImpl" public="true">
    <interface>com.stygian.jira.plugins.listeners.MyPluginComponent</interface>
</component>

delete-files

Delete the files highlighted in the image below.

###Step 3:

Run the command

atlas-create-jira-plugin-module

Select option 10 for JQL Plugin Module

Enter new class name: DateRangeJqlFunction
Enter package name: com.stygian.jira.plugins.jql
Show advanced setup: N
Add another plugin module: N

The SDK would have added the new component to your atlassian-plugin.xml

We will need to add a function name for our jql query. Edit your atlassian-plugin.xml (see the highlighted lnes below)

atlassian-plugin.xml

###Step 4:

The SDK would have now created a new java file called DateRangeJqlFunction that extends AbstractJqlFunction in your src/main/java/com/stygian/jira/plugins/jql folder. We will now being modifying this file and implementing our logic.

Open the file in your IDE and edit it as shown below.

package com.stygian.jira.plugins.jql;

import com.atlassian.crowd.embedded.api.User;
import com.atlassian.jira.component.ComponentAccessor;
import com.atlassian.jira.issue.Issue;
import com.atlassian.jira.project.Project;
import org.joda.time.DateTime;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import com.atlassian.jira.JiraDataType;
import com.atlassian.jira.JiraDataTypes;
import com.atlassian.jira.jql.operand.QueryLiteral;
import com.atlassian.jira.jql.query.QueryCreationContext;
import com.atlassian.jira.plugin.jql.function.AbstractJqlFunction;
import com.atlassian.jira.util.MessageSet;
import com.atlassian.jira.util.NotNull;
import com.atlassian.query.clause.TerminalClause;
import com.atlassian.query.operand.FunctionOperand;
import com.google.common.collect.Iterables;

import java.util.Collection;
import java.util.Collections;
import java.util.LinkedList;
import java.util.List;

/**
 * Echoes the the string passed in as an argument.
 */
public class DateRangeJqlFunction extends AbstractJqlFunction
{
    private static final Logger log = LoggerFactory.getLogger(DateRangeJqlFunction.class);

    public MessageSet validate(User searcher, FunctionOperand operand, TerminalClause terminalClause)
    {
        return validateNumberOfArgs(operand, 3);
    }

    public List<QueryLiteral> getValues(QueryCreationContext queryCreationContext, FunctionOperand operand, TerminalClause terminalClause)
    {
        final List<QueryLiteral> literals = new LinkedList<QueryLiteral>();
        try
        {
            Project project = ComponentAccessor.getProjectManager().getProjectObjByKey(operand.getArgs().get(0));
            Integer startDay = Integer.parseInt(operand.getArgs().get(1));
            Integer endDay = Integer.parseInt(operand.getArgs().get(2));
            if(startDay > endDay)
            {
                throw new Exception("Start day cannot be greater than end day");
            }
            if(startDay < 1 || startDay > 31 || endDay < 1 || endDay > 31)
            {
                throw new Exception("Days should be between 1 and 31.");
            }
            Collection<Long> issueIds = ComponentAccessor.getIssueManager().getIssueIdsForProject(project.getId());
            for(Long issueId:issueIds)
            {
                Issue issue = ComponentAccessor.getIssueManager().getIssueObject(issueId);
                DateTime issueUpdated = new DateTime(issue.getUpdated());
                if(issueUpdated.getDayOfMonth() > startDay && issueUpdated.getDayOfMonth() < endDay)
                {
                    literals.add(new QueryLiteral(operand, issueId));
                }

            }
        }
        catch(Exception exc)
        {
            log.error(exc.toString());
        }
        return literals;
    }

    public int getMinimumNumberOfExpectedArguments()
    {
        return 3;
    }

    public JiraDataType getDataType()
    {
        return JiraDataTypes.ISSUE;
    }
}

###Step 5:

Test the plugin by running the command atlas-debug

You can access your local instance at http://localhost:2990/jira. Login using the username admin and password admin and go to Administration -> Add-Ons -> Manage Add-on's and make sure your plugin is enabled.

Note: If there are errors, check your log file located in your plugin's target/jira/home/log directory.

verify-plugin

Perform a search using advanced search and running the following query

issue in dateRange(DEMO,5,10)

search-results