Remote Events

A standard event listener allows you to listen for and respond to events that occur in the current application. Remote events allow you to listen for events in a linked Bitbucket, Jira or Confluence instance. Bamboo will be available soon.

Examples of possible usage include:

1. Provisioning - when a project is created in Jira, create it also in Bitbucket and Confluence.

2. Synchronize Jira versions between instances - when you create a version in one Jira instance it appears in another

3. When a Jira version is created, automatically create a page in Confluence

When setting up a remote listener, you will select the linked application, then choose one or more events to handle. Under the covers, when the event is fired on the remote application, it will be serialized to JSON, then sent to the receiving instance. Upon arrival it’s republished as a local event and your listener will then respond to it.

It’s important to note that the event received is just a Map, and not the same type of event that you would get if it you were responding to a local event. The best way to start with remote events is to set up the remote listener, then log the event you get:

Select the application link which points to the application that you wish to receive events from. For the purposes of this example, we will receive an event from Bitbucket, but it doesn’t matter which event or which application you are using, the same technique applies:

The code sample above is the following. It simply dumps the content of the event to the log.

groovy
import groovy.json.JsonOutput

log.info "Remote event received: "
log.debug JsonOutput.prettyPrint(JsonOutput.toJson(event))

To test the handler, we will cause the event to be fired on the remote application, in this case by creating a new repository in Bitbucket.

If everything is set up correctly, on Jira you should see in your logs something like the following:

js
{
    "actor": {
        "active": true,
        "displayName": "Mr Admin",
        "emailAddress": "admin@example.com",
        "name": "admin",
    },
    "date": "2017-07-27T20:18:36+0000",
    "eventClass": "com.atlassian.bitbucket.event.repository.RepositoryCreatedEvent",
    "repository": {
        "forkable": true,
        "id": 14,
        "name": "thing",
        "project": {
            "id": 1,
            "key": "TEST",
            "name": "TEST",
            "public": false,
            "type": "NORMAL"
        },
    },
    "uuid": "0979b03b-afb6-464c-bc91-274dac63f937"
}
// some properties omitted

So, the event object is a Map with the properties above. To get the repository name you would use:

groovy
assert event.repository.name == "thing"

The project key for this repository:

groovy
assert event.repository.project.key == "TEST"

The user name that initiated this event on the remote system:

groovy
assert event.actor.name == "admin"

groovy
import com.atlassian.jira.component.ComponentAccessor

ComponentAccessor.jiraAuthenticationContext.loggedInUser

Example: Synchronize Jira Versions

In this example we have two Jira instances linked together. We’ll assume that there is at least one like-named project on both instances.

When the create version event arrives we will simply create a version in the same project on the local instance.

Line 13: Dump the JSON representation for debugging purposes

Most of this code relates to the fact that we don’t receive the dates as a Date class, so we need to parse them out. Dumping the event map will show you exactly what you are getting. See the documentation on remote events for an alternative way of accomplishing this.