JIRA

Install

Admin

Use

	JIRA Administrator's Guide Introduction Getting Help Look and Feel Logo, Colours and Timezone Configuring the default Language Configuring the default Issue Navigator Configuring the default Dashboard Overview of Dashboard Portlets Enabling Portlets and Other Plugins Editing the Announcement Banner Enabling Logout Confirmation Email Email Overview Creating a Notification Scheme Customising Email Content Creating Issues & Comments from Email SMTP configuration User Management Managing Users Managing Groups Managing Project Roles Migrating from Groups to Project Roles Enabling public signup and CAPTCHA Integrating JIRA with LDAP Integrating JIRA with Crowd Configuring Trusted Applications Security Overview Global permissions Project permissions Issue security Project Management Defining a Project Assigning members to Project Roles Defining Project Components Defining Project Versions Creating Release Notes for a Version Configuring Project Keys Configuring Fields and Screens Overview Defining 'Resolution' field values Defining 'Priority' field values Defining 'Status' field values Defining 'Issue Type' field values Associating Issue Types with Projects Translating Resolution/Priority/Status/Type Configuring field behaviour Configuring rich-text renderers Associating behaviour with Issue Types Placing fields on screens Associating screens with Issue Operations Associating screens with Issue Types Creating & configuring Custom Fields Custom Field Overview Adding Custom Fields Configuring Custom Fields Configuring Workflow Workflow Activating Workflow Events Importing from Other Systems Importing from Bugzilla Importing from Mantis Importing from FogBugz Importing from Excel/CSV Moving or Archiving Individual Projects Overview Archiving a project Merging JIRA instances Splitting JIRA instances Integrating with Source Control Integrating with CVS and ViewCVS Integrating with Subversion Integrating with Perforce Integrating with ClearCase Integrating with FishEye Configuration Options & Settings Global Settings Enabling Issue Linking Enabling Sub-tasks Enabling Trackback linking Enabling Time Tracking Enabling File Attachments Enabling Thumbnails for Attachments Server Administration Indexing & Search Backing up Data Automated Backups Restoring Data Database Integrity Checker Increasing memory Performance Tips Database Indexing Precompile JSP pages Logging and Profiling Thread Dump Downgrading (Ent to Pro) Downgrading (Ent to Std) Downgrading (Pro to Std) Using robots.txt with Search Engines Appendix A - Extending JIRA Extension Overview Listeners Listener Interfaces Example Listeners Registering a Listener Editing Listener Properti.. Removing a Listener Custom Events Services Jelly tags JIRA Toolkit Customising Text Developer Guides JIRA Plugins JIRA RPC Overview Creating a SOAP Client Creating an XML-RPC Client Creating Custom Field Types Custom Workflow Elements Creating new Portlets Creating new Reports More.. JIRA Source Building JIRA from source API Documentation

Listeners

PDF

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.

Listener Interfaces

There are currently two different concrete Listeners within JIRA (both of 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 (eg 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

To register a listener:

Make sure your listener class is in the classpath where JIRA can see it - the best locations are usually the WEB-INF/classes or WEB-INF/lib (as a JAR) directories within the JIRA web application.
Log in as a user with the 'JIRA System Administrators' global permission.
Bring up the administration page by clicking either the 'Administration' link on the top bar or the title of the Administration box on the dashboard:
Click the Listeners link in the System section of the left-hand navigation column.
Enter a Name (a nice name for this listener) and Class (the fully qualified class of your listener) for your listener and click Add.
The listener will now be added. Click Edit for your listener to edit its properties.

Editing Listener Properties

At any time you can edit a listeners properties by clicking Edit for that listener in the Listeners section of the Administration tab.

Removing a Listener

To remove a listener, just click Del for that listener in the Listeners section of the Administration tab.

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.