How do you programmatically raise a custom event?

[Nathon Fowlie]

Just wondering how you raise custom events from the Java API (using Jira 6.1.1)? I'm able to programmatically create a custom event type, but there doesn't seem to be an obvious ways of raising it?

I found the eventpublisher.publish() method but it takes a POJO as a parameter, so not sure how I'd associate the POJO with the custom event type? Has JIRA got some sort of undocumented smarts built into it so if I pass in a POJO with the right property name (ie: "EventType" or something similar) JIRA will be able to fire the right custom event?

Just to add to this, I'm trying to expose some project-level events in the Jira UI so admins can trigger notifications/scripts/workflows from things like the VersionRelease event.

[Boris Georgiev _Appfire_ · Accepted solution]

You have to pass an instance of the actual event to the com.atlassian.event.api.EventPublisher.publish(Object) method. The event can be a POJO it doesn't need to extend any special interface.

Then to listen to that event you have to annotate a method in a class with com.atlassian.event.api.EventListener annotation, so it is called when event is raised. Here's the javadoc of EventListener:

Methods should be public and take one parameter which is the event to be handled.

For example, the following class implements a simple event listener:

public class TestListener {
        @EventListener
        public void onEvent(SampleEvent event) {
            System.out.println("Handled an event: " + event);
        }
    }

And a sample how to raise that event would be:

SampleEvent event = new SampleEvent();
eventPublisher.publish(event);

[Nathon Fowlie]

Thx Boris. The bit I'm struggling with is where you raise the custom event. Originally I had hoped to just expose the builtin VersionRelease event but I don't know how I'd wire that up to an event type? Perhaps I'm looking at this whole thing from the wrong angle :/

When the "VersionRelease" event is fired, my event listener currently catches that. What I want is for the event listener to then fire my custom event type so that admins can use it as a trigger in script runner/notification schemes/JEMH/whatever. If I implement an event class, how do I make that class appear on JIRAs "events" page? Does it need to implement a specific class/interface or perform some sort of registration? Here's what I have so far:

public class VersionEventListener implements InitializingBean, DisposableBean {
    private static final Logger log = LoggerFactory.getLogger(VersionEventListener.class);
    private final EventPublisher eventPublisher;
    private final EventPublisher eventPublisher;
    private final EventTypeManager eventTypeManager;
    private final VersionManager versionManager;

    public VersionEventListener(EventPublisher eventPublisher, EventTypeManager eventTypeManager, VersionManager versionManager) {
        this.eventPublisher = eventPublisher;
        this.versionManager = versionManager;
        this.eventTypeManager = eventTypeManager;
    }

    public void afterPropertiesSet() throws Exception {
        eventPublisher.register(this);

        if (!eventTypeManager.isEventTypeExists("Version Released")) {
            eventTypeManager.addEventType(new EventType(
                500L,
                "Version Released",
                "Some description",
                13L // default 'generic event' template
            ));
        }
    }

    public void destroy() throws Exception {
        eventPublisher.unregister(this);
    }

    // TODO Cleanup custom events on plugin uninstall

    public void onVersionReleaseEvent(VersionReleaseEvent event) {
        log.info("Version was released...");

        // Step 4: ??? 
        // I want to fire my "Version Released" event type here, or better yet  
        // just expose the VersionReleaseEvent object somehow so the plugin 
        // isn't double-handling.

}
}

[Boris Georgiev _Appfire_]

You can extend AbstractEvent for your custom event. Then you can put the event type id (which can be an id of an existing event that you've created through the admin UI) inside your custom event class. Then you publish the event using the same method eventPublisher.publish(myCustomEvent);

[Nathon Fowlie]

Boris I still seem to be missing a step.

1. I extended AbstractEvent and created a "Long getEventTypeId()" method that returns a valid event type id.
2. I modified the default notification scheme to fire off a test "generic event" notification when the "Version Released" event type is raised.
3. I'm publishing my custom event via "eventPublisher.publish(new VersionReleasedEvent(eventTypeId, Version);"

Debug messages are sent to the console when the onVersionReleaseEvent method is called and when VersionReleasedEvent is instantiated, but the notification never gets raised? Seeing as AbstractEvent doesn't have a "getEventTypeId" method I also tried adding "eventTypeId" to the params map but to no avail :/

Do I have to call a custom post function from my event listener to make the event type fire?

[Nathon Fowlie]

Brilliant! Thx Boris :)