Aha! Develop | Event handler extension contributions

Event extension contributions run either in the browser or on the Aha! Develop servers. When running on the server, the event handlers run using the permissions of the user who installed the extension. Event extension contributions are also known as code-based automation.

Click any of the following links to skip ahead:

Definition

An event handler executes whenever its event is triggered anywhere in the account. Events can be triggered from other extension code via the aha.triggerBrowser and aha.triggerServer API in the browser or within server extension code. Events can also be triggered natively by Aha! Develop. Each time an event is triggered, all matching event handlers will be called. The order in which event handlers are called is not deterministic and multiple handlers for the same event may run at the same time. Event handlers can handle events triggered by any extension installed in the account, not just the extension in which the event handler is implemented.

Event names must include the full identifier of the extension, e.g. aha-develop.github.eventName.

Events provide a way for the functionality of an extension to be further extended or customized. The author of an extension should consider triggering events during any major operation even if those events are not consumed by the extension. These events provide a way for a user of the extension to easily hook their own behavior on top of the extension.

Top

package.json Schema

An extension that responds to the aha.create and aha.update.Feature.workflowStatus events would include package.json keys like:

  "ahaExtension": {
     "contributes": {
      "events": {
        "observer": {
          "title": "Event observer",
          "entryPoint": "src/observer.js",
          "handles": [
            "aha.create",
            "aha.update.Feature.workflowStatus"
          ]
        }
      }
    }
  }

entryPoint

Points to the JavaScript file implementing this contribution.

title

The human readable name of this event handler.

handles

An array of the event names that are handled by this contribution.

Top

API

aha.on({ event: 'aha.workflow-board.shipped' }, (arg, { identifier, settings }) => {
  aha.executeCommand('confetti-when-done.confetti');
});

  • arg — the argument that was provided to the aha.triggerBrowser or aha.triggerServer call.

  • identifier — set to the string identifier of the extension.

  • settings — the settings for the extension as a JSON object.

Top

Available events

Any extension can trigger events to be consumed by any other extension.

Aha! itself triggers events in response to record changes. Currently Aha! triggers events for changes to the Epic, Feature and Requirement record types.


create

update

destroy

Epic

X

X

X

Feature

X

X

X

Requirement

X

X

X

Comment

X


X

Aha! triggered event names follow the pattern: aha.{action}.{record type}.{field name}. Aha! will trigger multiple events from the same record change so that event handlers can listen for more or less specific classes of events. For example, a change to the workflow status of a feature will trigger the following events:

  • aha.update

  • aha.update.Feature

  • aha.update.Feature.workflowStatus

This allows an event handler to listen only for changes to status of a feature, or to listen for any field change on a feature.

The possible field names are:

  • name

  • workflowStatus

  • workflowKind (Feature only – corresponds to the Type field)

  • teamWorkflowStatus

  • assignedToUser

  • epic

  • iteration

  • release

  • team

  • originalEstimate

  • remainingEstimate

  • workDone

  • tags

Each event triggered by Aha! will have an argument with a shape like:

{
  user: // The user who made the change
  record: // The record that was changed
  event: // The name of the event
  changes: { // An object with a key for each changed field
    fieldName: {
      from: // The value the field changed from
      to: // The value the field changed to
    }
  }
}

For each changed field the format of the from and to values depends on the type of the field.

Top