Tutorial – Adding a JQL function to JIRA 6 – 7

Step 1. Create the plugin project

1. If you have not already set up the Atlassian Plugin SDK, do that now: Set up the Atlassian Plugin SDK and Build a Project.
2. Enter the following command to create a plugin skeleton:
   atlas-create-jira-plugin
3. Choose 1 for JIRA 5 when asked which version of JIRA you want to create the plugin for.
4. As prompted, enter the following information to identify your plugin:

   group-id	com.example.plugins.tutorial.jira
   artifact-id	jira-simple-jql-function
   version	1.0-SNAPSHOT
   package	com.example.plugins.tutorial.jira

5. Confirm your entries when prompted.

Step 2. Review and tweak the POM

1. Change to the new jira-simple-jql-function directory and open the pom.xml file for editing.
2. Add your company or organisation name and your website to the <organization> element (the following code blocks show how it looks in plain text): 
3. Update the <description> element: 
4. Save and close the file.

Step 3. Add your plugin modules

1. From the plugin root folder (where the pom.xml is located), enter the following command:
   atlas-create-jira-plugin-module
2. Choose the option labelled JQL Function.
3. Supply the following information as prompted:

   Enter New Classname	RecentProjectFunction
   Package Name	com.example.plugins.tutorial.jira.jql

4. Choose N for Show Advanced Setup.
5. Choose N for Add Another Plugin Module.
6. Confirm your choices.

Step 4. Review and tweak the plugin descriptor

1. Change to the src/main/resources/ and open atlassian-plugin.xml for editing.
2. Find the jql-function element and add two elements, fname and list, after the description, as shown here: 
3. Save and close the file.

Step 5. Write the plugin code

1. Change to the source code directory for our function, src/main/java/com/example/plugins/tutorial/jira/jql/
2. Open the RecentProjectFunction.java file for editing.

package com.example.plugins.tutorial.jira.jql;

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 com.atlassian.crowd.embedded.api.User;
import com.atlassian.jira.user.UserHistoryItem;
import com.atlassian.jira.user.UserProjectHistoryManager;
import java.util.LinkedList;

import java.util.Collections;
import java.util.List;

import com.atlassian.jira.user.ApplicationUser; //NOW COMPATIBLE WITH JIRA 6 & 7

public class RecentProjectFunction extends AbstractJqlFunction
{
private static final Logger log = LoggerFactory.getLogger(RecentProjectFunction.class);
private final UserProjectHistoryManager userProjectHistoryManager;
public RecentProjectFunction(UserProjectHistoryManager userProjectHistoryManager)
{
this.userProjectHistoryManager = userProjectHistoryManager;
}
public MessageSet validate(ApplicationUser searcher, FunctionOperand operand, TerminalClause terminalClause)
{
//NOW COMPATIBLE WITH JIRA 6 & 7
return validateNumberOfArgs(operand, 0);
}
public List<QueryLiteral> getValues(QueryCreationContext queryCreationContext, FunctionOperand operand, TerminalClause terminalClause)
{
final List<QueryLiteral> literals = new LinkedList<QueryLiteral>();
final List<UserHistoryItem> projects = userProjectHistoryManager.getProjectHistoryWithoutPermissionChecks(queryCreationContext.getUser());
for (final UserHistoryItem userHistoryItem : projects)
{
final String value = userHistoryItem.getEntityId();
try
{
literals.add(new QueryLiteral(operand, Long.parseLong(value)));
}
catch (NumberFormatException e)
{
log.warn(String.format("User history returned a non numeric project ID '%s'.", value));
}
}
return literals;
}
public int getMinimumNumberOfExpectedArguments()
{
return 0;
}
public JiraDataType getDataType()
{
return JiraDataTypes.PROJECT;
}
}

Step 6. Start JIRA and try out the plugin

1. Run atlas-run

More info in Atlassian