Last updated Jan 25, 2024

Events

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:

a site upgrading a Forge app to a new major version
any user updating a Jira issue
any user creating a Confluence space
a batch import process adding new Confluence pages
an app being added to a data security policy

See Types of event modules for more information about the events available in Forge.

Some use cases for apps that respond to events include:

An app that maintains and publishes to Confluence up-to-date custom statistics about Jira issue activities, which might subscribe to events related to the Jira issues and aggregate that information for publication.
"Pushing" new and updated data from an Atlassian product to another platform for external reporting. This is an alternative to running a client app on the other platform that periodically polls the Atlassian product using REST APIs and pulls the data to the other platform.

Considerations for apps that respond to events

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.

Configuring your app for events

To configure your app to respond to events:

Add a module to your manifest that specifies the events your app will respond to, and what it will do when it receives those events. For a quick start, you can specify a product-trigger, scheduled-trigger or webtrigger template when running forge create.
Add functionality to your Forge app to process the incoming event according to the details on the event's reference page. The table in this section contains links to the event reference pages.

Events are categorised by the module type used to configure them in the manifest.yml file, as described below.

Types of event modules

Module type Used to...

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: Jira Confluence Compass Bitbucket Forge application life cycle Data security policy If you are using `forge create` to create an app that includes a trigger module, choose the `product-trigger` template even when defining a module to respond to a lifecycle or data security policy event.
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.

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 forge create to create an app that includes a trigger module, choose the product-trigger template even when defining a module to respond to a lifecycle or data security policy event.

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.

Data associated with each module type

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.