Listeners
Listeners are unique to Jira, and a very powerful way to extend it.
Jira has a complete event subsystem that 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.
For all of the following procedures, you must be logged in as a user with the Jira system administrator global permissions.
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. |
com.atlassian.jira.event.issue.IssueEventListener | The main listener interface in Jira, used whenever anything happens to an issue. |
com.atlassian.jira.event.user.UserEventListener | This listener is called whenever anything happens to a user within Jira. |
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 — 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 — 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
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 of your Jira installation directory (as JAR files).
To register a listener:
- In the upper-right corner of the screen, select Administration
> System. - Select Advanced > Listeners to open the Listeners page.
- 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.
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.
- 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
- Tutorial - Writing Jira event listeners with the atlassian-event library — this describes how to write listeners using the Atlassian Events library (see Jira-specific Atlassian Events), rather than the Jira Listener Events described above.