Wiki

#JIRA Event Listener 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: ResolutionEventListener
version: 1.0.0
package: com.stygian.jira.plugins.listeners

atlas-create-jira-plugin

The above steps will create your plugin skeleton. You can now open this project in an IDE like IntelliJ Idea.

###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:

Now it is time to start working on our plugin. Start by registering your component by adding the following lines to the atlassian-plugin.xml file. I have also added a screenshot to help you figure out where to paste it in the atlassian-plugin.xml file.

<component-import key="eventPublisher" interface="com.atlassian.event.api.EventPublisher"/>
<component key="eventListener" class="com.stygian.jira.plugins.listeners.ResolutionEventListener">
    <description>Custom class where I can do something when an issue is resolved.</description>
</component>

add-component

###Step 4:

We will now write a class that will allow us to perform an operation when an issue is resolved. Since our class defined in the above component is com.stygian.jira.plugins.ResolutionEventListener, you will have to create the same folder structure within your src/main/java folder. Take a look at the screenshot below.

class-file

###Step 5:

Add the following to your ResolutionEventListener class

package com.stygian.jira.plugins.listeners;

import com.atlassian.event.api.EventListener;
import com.atlassian.event.api.EventPublisher;
import com.atlassian.jira.event.issue.IssueEvent;
import com.atlassian.jira.event.type.EventType;
import com.atlassian.jira.issue.Issue;

/**
 * User: bhushan154
 * Date: 08/07/13
 * Time: 8:43 PM
 * To change this template use File | Settings | File Templates.
 */
public class ResolutionEventListener {

    public ResolutionEventListener(EventPublisher eventPublisher) {
        eventPublisher.register(this);    // Demonstration only -- don't do this in real code!
    }

    @EventListener
    public void onIssueEvent(IssueEvent issueEvent) {
        Long eventTypeId = issueEvent.getEventTypeId();
        Issue issue = issueEvent.getIssue();
        if (eventTypeId.equals(EventType.ISSUE_RESOLVED_ID)) {
            //Perform your logic here
        }
    }
}

###Step 6:

Almost there. We just need to make our class implement InitializingBean and DisposableBean.

Add the following dependency in your pom.xml within the <dependencies> section.

<dependency>
    <groupId>org.springframework.osgi</groupId>
    <artifactId>spring-osgi-core</artifactId>
    <version>1.1.3</version>
    <scope>provided</scope>
</dependency>

Then update your code.

package com.stygian.jira.plugins.listeners;

import com.atlassian.event.api.EventListener;
import com.atlassian.event.api.EventPublisher;
import com.atlassian.jira.event.issue.IssueEvent;
import com.atlassian.jira.event.type.EventType;
import com.atlassian.jira.issue.Issue;
import org.springframework.beans.factory.DisposableBean;
import org.springframework.beans.factory.InitializingBean;

/**
 * Created with IntelliJ IDEA.
 * User: bhushan154
 * Date: 08/07/13
 * Time: 8:43 PM
 * To change this template use File | Settings | File Templates.
 */
public class ResolutionEventListener extends AbstractIssueEventListener implements InitializingBean, DisposableBean {

    private final EventPublisher eventPublisher = null;

    public ResolutionEventListener(EventPublisher eventPublisher) {
        this.eventPublisher = eventPublisher;
    }

    /**
     * Called when the plugin has been enabled.
     * @throws Exception
     */
    @Override
    public void afterPropertiesSet() throws Exception {
        // register ourselves with the EventPublisher
        eventPublisher.register(this);
    }

    /**
     * Called when the plugin is being disabled or removed.
     * @throws Exception
     */
    @Override
    public void destroy() throws Exception {
        // unregister ourselves with the EventPublisher
        eventPublisher.unregister(this);
    }

    @EventListener
    public void onIssueEvent(IssueEvent issueEvent) {
        Long eventTypeId = issueEvent.getEventTypeId();
        Issue issue = issueEvent.getIssue();
        if (eventTypeId.equals(EventType.ISSUE_RESOLVED_ID)) {
            //Perform your logic here
        }
    }
    public String getDescription()
    {
        return "This was a tutorial to developer a Jira custom listener.";
    }
}

###Step 7:

Test your plugin running the atlas-debug command.

Access the local instance on http://localhost:2990/jira and login using the username "admin" and password "admin".

Go to Administration -> Add Ons and select Manage Add-Ons.

##Installing your listener upon Jira startup

You can choose to install a listener upon Jira startup. To do so, create a class that implements com.atlassian.jira.extension.Startable. See example below.

package com.stygian.jira.plugins.listeners;

import com.atlassian.jira.component.ComponentAccessor;
import com.atlassian.jira.extension.Startable;
import java.util.Iterator;
import java.util.Map;
import org.apache.log4j.Logger;



public class InstallListener
        implements Startable
{
    private static final Logger log = Logger.getLogger(InstallListener.class);

    public void start() throws Exception
    {
        installListener();
    }

    private void installListener()
    {
        if (!isListenerInstalled())
        {
            try
            {
                ComponentAccessor.getListenerManager().createListener("Provide a description of your listener plugin",ResolutionEventListener .class );                
            }
            catch (Exception e)
            {
                log.error("Error adding listener: " + e.toString() + ".");
            }
        }
    }

    private boolean isListenerInstalled()
    {
        Map m = ComponentAccessor.getListenerManager().getListeners();
        Iterator it = m.entrySet().iterator();
        while (it.hasNext()) {
            Map.Entry entry = (Map.Entry)it.next();
            if ((entry.getValue() instanceof ResolutionEventListener )) {
                return true;
            }
        }
        return false;
    }
}

In your atlassian-plugin.xml file, replace the listener component lines you had entered earlier with

<component key="resolution-event-listener-init" name="Install the resolution event listener" class="com.stygian.jira.plugins.listeners.InstallListener">
        <description>Automatically install the resolution event listener on JIRA startup.</description>
    </component>