Your app can subscribe to events or set up an HTTP endpoint to invoke a function within your app without any user interaction.
This enables the app to respond to activities occurring on the back end of Atlassian products and the Forge platform whether they resulted from any user's interaction with the product or other processing behind the scenes such as a REST API based script that made bulk updates to your projects.
Examples of the many product and platform events your app can listen for include:
See Types of event modules for more information about the events available in Forge.
Some use cases for apps that respond to events include:
Some special considerations apply when developing an app that responds to events, that do not apply to apps that run within a user's interactive session.
App code that responds to events does not have access to the product's user interface and is not linked to any user's session. Therefore, if you try to retrieve additional data about the event
from the useProductContext
hook, you will find that it includes a limited amount of information compared to the product context for interactive sessions.
However, your app can include separate UI modules that respond to the current user's product interactions, if desired.
Additionally, app code that responds to events runs under the identity of the app system user, rather than an Atlassian interactive user account. If you have specified permissions for a resource such as a Confluence page or Jira project that only allow certain Atlassian user accounts access to it, your application may not be able to access that resource when handling a received event because the app system user may not have permission to do so.
To configure your app to respond to events:
product-trigger
, scheduled-trigger
or webtrigger
template when running forge create
.Events are categorised by the module type used to configure them in the manifest.yml
file, as described below.
Module type | Used to... |
---|---|
trigger | Notify your app when selected platform and platform events occur. To learn about specific product and platform events your application can respond to using a trigger module, see: If you are using |
scheduled trigger | Invoke your app on a periodic basis, such as once per hour. |
web trigger | Register an endpoint that can accept HTTP requests, including third party requests, made to your app's registered URL. |
Each of the event module types has:
A set of properties specific to that module type, that you use to configure the module in the manifest.
For example, the trigger
module requires that you specify a key that uniquely
identifies that module in the manifest, a function or endpoint (for Forge remote) to run when the event occurs, and the list of events that module is subscribing to.
For more information, see the Scheduled Trigger, Trigger, and Web trigger manifest reference topics.
(Product, data security policy, and lifecycle events only) An additional set of properties specific to the event being configured.
For example, when an event notifies your app about comments added in Confluence, it includes the name of the event, the atlassian ID of the user whose action prompted the event, and an object representing the comment, including the page ID and space of the page being commented on.
See the event-specific topics in the Events reference area for more information.
A context object that provides more information about the context the event occurred in, such as the installation ID of rhe Atlassian site the app is installed in.
Rate this page: