Adding a custom event

Jira uses an event-listener mechanism to alert the system that something has happened, and to perform appropriate action (e.g. send an email notification) based on the event that has occurred. Every issue operation within Jira is associated with a particular event - e.g. the Issue Created event is fired when an issue has been created.A listener can execute a specified action once it has been notified that a particular event has been fired. For example, the MailListener can send an Issue Created email to a list of recipients defined in the appropriate notification scheme, whenever an issue is created.

Some events are fired by Jira internally — e.g. an Issue Updated or Issue Moved event. Other events are fired from within workflow transition post functions — e.g. an Issue Resolved event, or a custom event (see below).

There are two types of events within Jira:

  • System — System events are used throughout Jira internally, and cannot be added or deleted. You can, however, make them Inactive (see below).
  • Custom — Custom events are used to generate an email notification (or invoke a listener) from a particular workflow transition's post function. You can add and delete as many custom events as you need. Note that only inactive custom events can be deleted.

An event can be in either of the following states:

  • Active — the event is associated with at least one notification scheme or workflow transition post function.
  • Inactive — the event is not associated with any notification schemes or workflow transition post functions.
    Note that the event state does not indicate whether the event is able to be fired. A custom event will only be fired if it is associated with a transition post function for an active workflow (see Managing your workflows).

System events

Jira's built-in system events are:

Issue created

An issue has been entered into the system.

Issue updated

An issue has had its details changed.

Issue assigned

An issue has been assigned to a new user.

Issue resolved

An issue has been resolved (usually after being worked on and fixed).

Issue closed

An issue has been closed. (Note that an issue may be closed without being resolved; see statuses).

Issue commented

An issue has had a comment added to it.

Issue comment edited

An issue's comment has been modified.

Issue reopened

An issue has been re-opened.

Issue deleted

An issue has been deleted.

Issue moved

An issue has been moved into this project.

Work logged on issue

An issue has had hours logged against it (i.e. a worklog has been added).

Work started on issue

The Assignee has started working on an issue.

Work stopped on issue

The Assignee has stopped working on an issue.

Issue worklog updated

An entry in an issue's worklog has been modified.

Issue worklog deleted

An entry in an issue's worklog has been deleted.

Generic event

The exact nature of this event depends on the workflow transition post function(s) which invoke it. As with custom events, you can use the generic event to generate an email notification (or invoke a listener) from a particular workflow transition's post function (see Working with workflows).

Custom events

You can fire a custom event from a custom transition post function in a custom workflow. The appropriate listeners will be alerted of the custom transition by the firing of this event. For example, the associated notification scheme can be configured to notify users of the workflow transition based on the firing of this custom event.

Configuring notifications for a custom event

Custom events are most commonly used to generate notifications for custom workflow transitions. For example, your organization might need you to modify the default workflow by adding a workflow step called 'QA_Inspection' (e.g. between Resolve issue and Close issue). You would typically also need to generate an email notification to the QA team whenever an issue progresses to the 'QA_Inspection' step of the workflow.

There are three overall steps to achieve this:

  1. Add a custom event to the system (e.g. 'Issue Awaiting QA').
  2. Configure the notification scheme to send an email when the custom event is fired.
  3. Configure the workflow transition post function to fire the custom event.

Adding a custom event

  1. Log in as a user with the Jira Administrators global permission.
  2. Choose Administration () > System. Select Advanced > Events to open the View Events page.
  3. In the Add New Event form at the bottom of the page, add a name and description for the custom event.
  4. In the Template field, select the default email template to be associated with the event.
  5. Select Add.

The custom event must be associated with a default email notification template. A notification scheme configured to notify users of this event will use this email template when sending the notification.

The custom event will appear in the list of events defined within the system. Initially, the event will be marked as inactive, as it is not associated with a notification scheme or workflow post function.

Configuring the notification scheme to send mail

  1. Log in as a user with the Jira Administrators global permission.
  2. Choose Administration () > System. Select Advanced > Events to open the View Events page.
  3. Select the notification scheme to edit, by selecting the notification scheme's name or its Notifications link (under Operations).
  4. Add the recipients for the custom event as required. See Creating a notification scheme for more information.

Configuring a post function to fire the custom event

  1. Log in as a user with the Jira Administrators global permission.
  2. Choose Administration () > Issues. Select Workflows to open the Workflows page, which displays all of the workflows in your system.
  3. Navigate to workflow transition post function screen to be edited. See Working with workflows and Advanced workflow configuration for more information.
  4. Update the post function to fire the custom event.
  5. Activate or associate the workflow (and scheme) with the appropriate project. See Managing your workflows for more information.
Last modified on Jul 19, 2022

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.