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

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

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.

Handling cascading events in Jira

In Jira product events, the relationship between entities is hierarchical, structured as follows:

• Project: The top-level entity.
  • Issue: Child of project.
    • Worklog: Child of issue.
    • Comment: Child of issue.
    • Attachment: Child of issue.
  • Board: Associated with project through board location.
  • Component: Child of project.
  • Version: Child of project.
  • Issue type: Child of team-managed project.

Understanding this hierarchy is key to managing events, especially delete events, which cascade down the hierarchy.

Handling delete events

When a project is deleted in Jira, all its descendants (issues, worklogs, comments, attachments) or associated entities (eg. boards) 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, associated boards, versions, components or issue types.

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, attachments, boards, versions, components, and issue types you'll need to implement a workaround to handle cascading deletes at the project or issue level.

Workaround for handling cascading deletes

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:

1. Listen for delete events of higher-level entities if you want to be notified about removal of lower-level entites: Initially, ensure your app is set up to listen for delete events at the project and issue levels. This will be your trigger to check for cascading deletes.
2. Fetch and save entity structure before deletion: Before a project or issue is deleted, store a list of all associations between entities that your app needs to track. This can be done by using Jira's REST API to query for all issues under a project and subsequently all worklogs, comments, and attachments for those issues.
3. Handle deletes manually in your app: Once you have the list of all entities that will be deleted, your app can then manually process these deletes in a way that suits your application's needs. This could involve removing references to these entities from your app's database, triggering specific cleanup processes, or logging the deletions for audit purposes.

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.

Best practices

• 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, attachments, boards, versions, components, or issue types, 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.