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'll 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.
In Jira product events, the relationship between entities is hierarchical, structured as follows:
Understanding this hierarchy is key to managing events, especially delete events, which cascade down the hierarchy.
When a project is deleted in Jira, all its descendants (issues, worklogs, comments, attachments) are also removed. However, it's important to note:
We only emit a delete event for top-level entities.
When a project is deleted, we won't emit separate delete events for its child issues.
The same applies to the descendants of an issue (worklogs, comments, attachments) when its parent is deleted.
This means that if your app relies on receiving delete events for individual issues, worklogs, comments, or attachments, you'll need to implement a workaround to handle cascading deletes at the project or issue level.
To effectively manage cascading deletes and ensure your app can react to these events, you should store an up-to-date copy of the entire project hierarchy structure. To achieve this consider the following approach:
Example pseudocode for handling cascading deletes:
1 2// Example function to handle project deletion function onProjectDelete(projectId) { // Read all issues for the project based on previously stored association const issues = readCachedIssuesForProject(projectId); // For each issue, read and handle descendants issues.forEach(issue => { const worklogs = readCachedWorklogsForIssue(issue.id); const comments = readCachedCommentsForIssue(issue.id); const attachments = readCachedAttachmentsForIssue(issue.id); // Handle deletion of worklogs, comments, and attachments here // For example, remove references from your app's DB handleDelete(worklogs, comments, attachments); }); // Finally, handle the deletion of issues at your app level handleDelete(issues); } // Note: `readCachedIssuesForProject`, `readCachedWorklogsForIssue`, `readCachedCommentsForIssue`, // `readCachedAttachmentsForIssue`, and `handleDelete` are placeholders for functions you would need // to implement based on your app's architecture and the specifics of the Jira REST API calls. // These functions are intended to demonstrate the logical flow for handling cascading deletes.
Implement robust error handling: When dealing with cascading deletes, ensure your app gracefully handles errors. For instance, if fetching descendants of an issue fails, your app should log this error and proceed with the next steps cautiously.
Optimize API calls: Fetching a large number of entities can be resource-intensive. Optimize your API calls by using bulk operations (like Jira expressions) wherever possible and by limiting the fields returned to only those necessary for your deletion logic.
Keep track of dependencies: If your app creates additional entities or relationships based on issues, worklogs, comments, or attachments, ensure you have a mechanism in place to track and handle these dependencies when the parent entities are deleted.
Regularly review API changes: Jira's REST API and Forge platform are continually evolving. Regularly review Atlassian's documentation for any changes that might affect how delete events and entity hierarchies are managed.
Rate this page: