Documentation for JIRA 6.3 EAP developer (EAP) releases only. Not using this? See below:
(JIRA 6.2.x documentation | JIRA OnDemand documentation | earlier versions of JIRA)

Skip to end of metadata
Go to start of metadata

JIRA uses an event-listener mechanism to alert the system that something has happened, and to peform 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).

On this page:

Overview

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/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 Activating workflow).

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 Workflow and Notifications ).

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 organisation 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 > System. Select Advanced > Events to open the View Events page.
    (tick) Keyboard shortcut: g + g + start typing events
  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. Click the Add button.

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 > Issues. Select Notifications Schemes to open the Notification Schemes page.
    (tick) Keyboard shortcut: g + g + start typing notification schemes
  3. Select the notification scheme to edit, by clicking 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 > Issues. Select Workflows to open the Workflows page, which displays all of the workflows in your system.
    (tick) Keyboard shortcut: g + g + start typing workflows
  3. Navigate to workflow transition post-function screen to be edited. See Configuring Workflow and  Applying Post Functions to Transitions 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 Activating workflow for more information.

15 Comments

  1. Anonymous

    This page would be a lot more helpful with information about creating your own email template or at least a blurb indicating that it is not possible.

  2. Anonymous

    Is it possible to create a notification scheme such that an email is sent when an issue of a particular type is created. i.e. on 'Issue Created' system event for issue type Bug, an email is sent to abc@abc.com

  3. Anonymous

    Hello all,

    I am creating a new Worflow that allows people to ask more information of the concerning issue, and I want to use a Listener to perform so. We would like to notify users when this status "Ask for more info" is reached, via the transition "Ask for more info".

    I have implemented the following steps:

    1) Create a new template issueaskmoreinfo.vm, generating new files within directories

    <JIRA_HOME>/atlassian-jira/WEB-INF/classes/templates/email/html
    <JIRA_HOME>/atlassian-jira/WEB-INF/classes/templates/email/text
    <JIRA_HOME>/atlassian-jira/WEB-INF/classes/templates/email/subject
    
     

     2) I have updated the file email-template-id-mappings.xml, adding the new event

        <templatemapping id="10000">
            <name>Ask For More Info Event</name>
            <template>issueaskmoreinfo.vm</template>
            <templatetype>issueevent</templatetype>
        </templatemapping>

     

    3) Added a new entry on file upgrade-system-event-types.xml:

        <eventtype id="10000">
            <i18n-name-key>event.type.genericevent.name</i18n-name-key>
            <i18n-description-key>event.type.genericevent.desc</i18n-description-key>
            <name>Ask for More info Event</name>
            <description>This is the 'Ask for More info Event' event type.</description>
            <notificationName>ISSUE_ASKMOREINFO</notificationName>
            <eventName>askformoreinfoevent</eventName>
        </eventtype>

     

    4) I have created the new event from the JIRA UI and added it to the workflow, as a post-function within the transition towards "Ask for more info" status.

    <function type="class"><arg name="class.name">com.atlassian.jira.workflow.function.event.FireIssueEventFunction</arg><arg name="eventTypeId">10000</arg></function>

     

    5) A listener to handle the events has been created and added to the project:

     

    class AfterCommentListener extends AbstractIssueEventListener implements IssueEventListener{
        Category log = Category.getInstance(AfterCommentListener.class)
    
        @Override
        public void workflowEvent(final IssueEvent event)
        {
            log.warn "Event: ${event.getEventTypeId()} fired for ${event.issue} and caught by JIRAListener"
    
            switch(event.getEventTypeId()){
                case ISSUE_CREATED_ID: //New issue
                    log.warn "ISSUE_CREATED_ID: "+ event.getIssue()
                    prepareMailIssueCreated (event)
                    break
                case 10000: //Ask for more info
                    log.warn "Ask for more info: "+ event
                 break
                case ISSUE_COMMENTED_ID:
                    log.warn "ISSUE_COMMENTED_ID"
                    prepareMailIssueCommented (event)
                    break
                case ISSUE_CLOSED_ID:
                    log.warn "ISSUE_CLOSED_ID"
                    prepareMailIssueClosed (event)
                    break
                default:
                    log.warn "DEFAULT" + event
                    break
            }    }

     

    BUT

     

    When changing to status "Ask more info", nothing happens. The event is not fired, and thus, the listener is not used.

    On the other hand, events are fired when other actions happen (creating issue, commenting it, etc), as seen in logs:

    2012-11-12 10:44:59,244 http-8081-1 WARN rodmarc 644x89x1 1grv4xv 127.0.0.1 /secure/WorkflowUIDispatcher.jspa [jira.AfterCommentListener] Event: 13 fired for TEST-6 and caught by JIRAListener
    2012-11-12 10:44:59,247 http-8081-1 WARN rodmarc 644x89x1 1grv4xv 127.0.0.1 /secure/WorkflowUIDispatcher.jspa [jira.AfterCommentListener] DEFAULTcom.atlassian.jira.event.issue.IssueEvent@1ab1d4a[issue=TEST-6,comment=<null>,worklog=<null>,changelog=[GenericEntity:ChangeGroup][id,10504][author,rodmarc][created,2012-11-12 10:44:58.622][issue,10104],eventTypeId=13,sendMail=true,params={eventsource=workflow, baseurl=http://localhost:8081},subtasksUpdated=false]

     Does anybody see what I am missing or doing wrong?

     

    Thanks!

    Marc

     
  4. Anonymous

    I want to have a status of "Ready For Review" where at that point the assigned QA person adds "Review - Subtasks" assigned to each reviewer.  I want to then have 3 ways to status those subtasks - "Approve", "Approve with Comments", and "Reject" to complete them.  The QA person creates the review subtasks and then moves the parent JIRA issue to a status of "In Review".   I want the "In Review" status to automatically transition to "Review Complete" once all of the "review subtasks" have been completed.   How do I do this? 

    1. I think Atlassian Answers is a better place for your question. That being said, what you're looking to accomplish is feasible with JIRA, you have two approaches.

      1) No plugin needed: Write a jelly script that looks at all the issues with "In Review" status, and checks if all the review sub tasks are completed, then transitions to "Review Complete".

      2) Plugin needed: Use the Script Runner plugin. Write a scripted post-function that you'll use in the workflow for your "Review - Subtasks". 

      The main difference: Jelly script will run periodically (say, every 5 minutes) through a JIRA service, while the transition post-condition will happen right away.

      If you haven't done any scripting in JIRA, be aware there's a learning curve.

  5. Anonymous

    I want to to automatically send out an email notification based on the Priority and Issue Type of a specific project to my team.  The notification should go out upon the creation and resolution of the issue.

    So, when Priority = Critical and Issue Type = Bug I would like the members of his particular project to receive an email when the issue is opened and resolved. 

    Is it possible to send out notifications based on this criteria?

    Please let me know if anyone can help. Cheers!

    1. You cannot do that in Vanilla JIRA, but it may be possible using the Script Runner plugin.

      You would create a new post function that would fire the event (and therefore the notification) based on the priority.

      You may want to look at the following entry from Atlassian Anwsers: How to send auto email notification based on priority level

      Also do have a look at the comments of  JRA-2115 - Ability to create Notification Scheme based on issue priority Open

  6. Anonymous

    Hello, I am trying to modify an existing html email template (issuecreated.vm) to include a custom field value (Customer name).

    I copied and edited the line #parse("templates/email/html/includes/fields/assignee.vm") in the issuecreated.vm file to #parse("templates/email/html/includes/fields/customer.vm"), and created the customer.vm file in the fields dir by copying the assignee.vm file and changing it. 

    My problem is that the email shows the line as Assignee: "customer name"(extracted correctly from the custom field), and I am not sure how and where I need to change the template or any other file so that the text "Assignee:" will be changed to "Customer:"

    I am a complete novice in working with JIRA and velocity, so any help here would be greatly appreciated...

    Thanks 

  7. Anonymous

    Hello, JIRA sends emails whenever there are changes to any of the fields, since "Issue Updated" is in the default notification scheme.  Is it possible to not send an update on when certain fields, like Due Date or custom fields get updated?  Thank you.

  8. In the following area, the instructions are extremely ambiguous.

    •  Step 3. Configure Workflow Transition Post-Function to Fire Custom Event
      • 4. Update the post-function to fire the custom event.


    Nowhere does it indicate that there will already be a Post-Function called Fire Generic Event which you then change in order to fire your Custom Event.  I wasted more time than I'd care to admit as the instructions indicate that you are adding a Post-Function, not altering a previously existing one.

    Future revisions of this document should be more clear.


  9. Hi all,

    im just complaining about what event to fire when finish testing (custom transition: "Verified") which leads into status "Closed". Does the system event "Issue Closed" cause any other functions beside the notification mail? I want to use a custom event "Issue tested" as the mails will look different from the "Issue Closed" event...

  10. Greetings,

    When an issue has blocks type links to other issues and transitions to resolved I would like to send email notifications to the assignees of the linked issues. Is that possible?

    Example: Issue A has two links blocks issue B and blocks issue C. When A is resolved, an email is sent to assignee of B and assignee of C, who can then work on that issue. Is that possible at all?

  11. Anonymous

    We currently have the default workflow implemented within JIRA projects.  I'd like to add a step to default workflow so that whenever a developer sets a defect to fixed, it automatically notifies the tester and updates resolution to "Ready for QA".  How would that look within default workflow?  Also I'd like to allow the option for a developer to select "Ready for QA" once a developer task within a user story is ready for QA to test.  Would greatly appreciate some help here.

    Thanks.

     

  12. Anonymous

    Is it possible to add an event that will fire after a period of time. 

    Example, I want to add a new task that will begin after 1 week, The status will open, after 1 week it will automatically change the status to "Start  process" and automatically will assign the task to a user.