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.
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.
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.
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.