Listeners

Listeners are unique to JIRA, and a very powerful way to extend it.

JIRA has a complete event subsystem which fires events whenever anything happens inside the application. For example an ISSUE_CREATED event is fired whenever an issue is created.

A Listener is a class that implements one of the Listener interfaces. It is then called whenever events occur in JIRA. Using those events, you can then perform any action you want. For example the email sent by JIRA is driven by the MailListener.

Listeners are most useful when you want to drive or affect external systems from events which occur within JIRA.

On this page:

Listener Interfaces

JIRA has the following concrete Listeners (which extend the base JiraListener interface):

com.atlassian.jira.event.JiraListener

The base interface which all other JIRA listener interfaces extend. Covers core listener properties like uniqueness, description, parameters etc.
API doc

com.atlassian.jira.event.issue.IssueEventListener

The main listener interface in JIRA, used whenever anything happens to an issue.
API doc

com.atlassian.jira.event.user.UserEventListener

This listener is called whenever anything happens to a user within JIRA.
API doc

Example Listeners

The examples provided may be freely used and modified for use in your own environment. The source of all examples is available and should give you good overview of how simple it is to write your own listeners. Both example listeners are included with JIRA 2.1, and both implement UserEventListener and IssueEventListener.

  • DebugListener (source) — This is a very simple listener that prints events and their content to System.out whenever they are received. To test this listener, add a listener with the class com.atlassian.jira.event.listeners.DebugListener .
  • MailListener (source) — This listener is how mail notifications are currently sent from within JIRA, and a good example of a more complex listener. It basically listens for events, and turns them into email notifications using Velocity templates to generate the mail bodies.
    This listener is usually always turned on in JIRA — see Email Notifications for more details. If you want to write more complex or more specific notifications, you can disable the internal MailListener and add your own.

Other examples of useful tasks that can be accomplished with listeners are:

  • Send SMS or IM notifications — A listener could easily send notifications for various events via SMS or instant messenger (e.g. ICQ or AIM) - or anywhere that you have a Java library to send messages.
  • Group notifications — A listener could notify certain groups of issue changes, depending on the content of the issue. For example any issue containing "windows" in the environment could notify your "windows-developers" group.

Registering a Listener

(info) For custom-written listener classes, make sure your listener class is in the classpath where JIRA can see it — the best locations are usually the <jira-application-dir>/WEB-INF/classes or <jira-application-dir>/WEB-INF/lib subdirectories within of your JIRA Installation Directory (as JAR files).

To register a listener:

  1. Log in as a user with the 'JIRA System Administrators' global permission.
  2. Choose > System. Select Advanced > Listeners to open the Listeners page.
    (tick) Keyboard shortcut: 'g' + 'g' + type 'lis'
  3. In the 'Add Listener' form at the bottom of the page, complete the following fields:
    • 'Name' — an appropriately descriptive name for the listener.
    • 'Class' — the fully-qualified class name of your listener.

      (info) To use one of JIRA's built-in listener classes, first click the 'Built-in Listeners' link to expand the list of listener classes and then click the name of the specific class in the list. The fully-qualified class name of the built-in listener will be added to the 'Class' field.
  4. Click the 'Add' button and the listener will now be added to the list of listeners above.

Editing Listener Properties

If your listener accepts parameters or properties, you can edit these by clicking the 'Edit' link associated with your listener (on the 'Listeners' page in JIRA's Administration area).

When defining your own Listener, there is a method getAcceptedParams to overload for defining the parameter names which are passed as an array of String objects. The init method is given a Map with the configured values (the JavaDoc is outdated). The com.atlassian.jira.event.listeners.DebugParamListener class is a good example of doing this with two parameters.

Removing a Listener

To remove a listener, click the 'Delete' link associated with that listener (on the 'Listeners' page in JIRA's Administration area).

Custom Events

With the ability to add custom events to JIRA, the Listener must be updated to deal with the event as appropriate. This is possible by providing an implementation for the method customEvent(IssueEvent event) in the Listener. For example, the MailListener implementation passes the custom event on for notification processing. The DebugListener logs that the custom event has been fired.

See Also

Was this helpful?

Thanks for your feedback!

20 Archived comments

  1. User avatar

    saleheddine abdessaied

    Hi,

    I want just to mention that there is no way to disable Jira Internal Listener from Dashboard .

    Please if Some one find how to make that possible ,just contact me

    Regards

    26 Mar 2010
  2. User avatar

    Tapas Mondal

    I want to trap the event during issue linking time.

    Please help

    23 Nov 2010
  3. User avatar

    Anonymous

    I have a ploblem. I wrote source of my listener plugin and my class always marked like "internal" after adding, and I have no ability to remove it. Besides, all events are not initialized. Plugin just ignored te overriding methods.

    14 Dec 2010
  4. User avatar

    Valentijn Scholten

    The example listeners don't ouput any logging for me. Do I need to change some logging levels? The examples talk about System.out and System.err

    19 Mar 2011
    1. User avatar

      Cory Sytsma

      They didn't produce any log output for me either.  I used log4j instead, and got the log output I was looking for.

      15 Apr 2011
  5. User avatar

    Anonymous

    how to trap issue clone event?

    13 Apr 2011
    1. User avatar

      ohmkaar kambhampati

      how to trap issue clone event? any answer for this?

      03 Apr 2013
      1. User avatar

        Matt Doar (ServiceRocket)

        Looking in Notification Schemes and EventType.java I don't see an ISSUE_CLONE event. Is this a custom event you created perhaps?

        03 Apr 2013
  6. User avatar

    Anonymous

    Hi,

    I created a dummy plugin listener, my class implements IssueEventListener, UserEventListener, however I only get call from UserEventListener but not from IssueEventListener, is there anybody who faced the similar problem, what could be the mistake there?

    13 Jul 2011
  7. User avatar

    Yukihiro Sakamoto

    Hello,

    I have a question how to output error message on web browser from IssueEventListener. I want to tell some error messages to an user who made the event. If I use "System.err.println()" to output error messages, they are written to a log file (catalina.out) on JIRA server. But it is very difficult for the user to know that the error occured. Are there any ways to display messages on client browser ?

    17 Aug 2011
  8. User avatar

    Kevin Mote

    The first link in the "See Also" section is broken. I believe it should point to: https://developer.atlassian.com/display/JIRADEV/Writing+JIRA+event+listeners+with+the+atlassian-event+library

     

    15 Nov 2012
  9. User avatar

    Ramiro Pointis

    API Docs links are not working, It shows a 'Forbidden' message.

    30 Apr 2013
    1. User avatar

      Matt Doar (ServiceRocket)

      Ack, that's annoying. The top-level URL at http://docs.atlassian.com/software/jira/docs/api/ does still work

      30 Apr 2013
      1. User avatar

        Ramiro Pointis

        Yes, I've tried a few things and I noticed the problem is in the /latest/ directory. If you put other version like /4.0/ you don't have problems.

        P.S. I'm almost sure the captcha for the comments isn't working properly, I'm sure I wrote well the captcha but it says it's not the same :-/

        30 Apr 2013
        1. User avatar

          Matt Doar (CustomWare)

          The captcha fails the first time for me too. Perhaps they're http://craptchas.com/

          30 Apr 2013
          1. User avatar

            Andrew Lui [Atlassian Technical Writer]

            Hi Matt and Ramiro,

            I'm not aware of any problems with the CAPTCHA. I just tried it and it worked first time for me. If the problem persists, could you raise a support request?

            Kind Regards,
            Andrew

            30 Apr 2013
    1. User avatar

      Andrew Lui [Atlassian Technical Writer]

      Hi,

      Can you please try again? I checked and it is working for me (e.g. this link). We had a temporary outage yesterday due to some work on the docs.atlassian.com server, and it unexpectedly caused problems with the links with the "latest" directory. You may need to clear your browser cache.

      If the problem still occurs, please raise support request for further assistance.

      Kind Regards,
      Andrew

      30 Apr 2013
      1. User avatar

        Matt Doar (CustomWare)

        Working for me now. But captchas never work the first time

        30 Apr 2013
        1. User avatar

          Matt Doar (CustomWare)

          Unless I do a Preview. No Preview = failure

          30 Apr 2013
          1. User avatar

            Matt Doar (ServiceRocket)

            Andrew,

            More breakage around the "latest" doc URL:

            http://docs.atlassian.com/jira/REST/latest/

            is giving a 403 at the moment in Chrome and Firefox with cleared caches

            01 May 2013
Powered by Confluence and Scroll Viewport