Use a long-running function

By default, async event consumers time out after 55 seconds. Use cases that required longer computation have had to rely on breaking the task into multiple steps or batches, and queuing multiple events to do the work.

You can now configure a timeout of up to 900 seconds (15 minutes) which will allow many such use cases to be performed in a single invocation.

Use Case: Generating Reports from Jira Data

Imagine you are developing an application that generates detailed reports from Jira issues. This process can be time-consuming, especially if you are aggregating data from multiple projects and applying complex calculations. The Long-Running Compute feature allows you to handle these tasks efficiently without running into timeout issues.

Before you begin

This tutorial assumes you're already familiar with developing on Forge and the Async Events API.

Before you start, ensure you have the following:

• An Atlassian account with access to Forge.
• The Forge CLI installed on your machine.
• Basic knowledge of JavaScript and Forge development.

Step 1: Set Up Your Forge Application

1. Create a new Forge app:

   1
   2
   forge create
   

   Follow the prompts to set up your application. Name your app and choose the template appropriate to the type of app you are creating. For the purposes of this tutorial the blank template will work fine. If you intend to extend this example with a UI to trigger the long-running function you can select a template from the UI Kit category.
2. Navigate to your app directory:

   1
   2
   cd your-app-name
   

3. Add necessary permissions: Open manifest.yml and add the required permissions to access Jira data:

   1
   2
   permissions:
     scopes:
       - read:jira-work
   

Step 2: Implement the long-running function

1. Create a new function: In your app directory, create a new file called generateReport.js:

   1
   2
   import { invoke } from '@forge/api';
   
   export const handler = async (event) => {
       const { projectKey } = event;
   
       // Simulate a long-running task
       const reportData = await generateReport(projectKey);
   
       return {
           statusCode: 200,
           body: JSON.stringify(reportData),
       };
   };
   
   const generateReport = async (projectKey) => {
       const issues = await fetchIssuesFromJira(projectKey);
       // Perform complex calculations and aggregations
       const report = performCalculations(issues);
       return report;
   };
   
   const fetchIssuesFromJira = async (projectKey) => {
       // Simulate a delay for fetching data
       await new Promise(resolve => setTimeout(resolve, 5000));
       // Return mock data
       return [
           { id: 1, status: 'Done', points: 5 },
           { id: 2, status: 'In Progress', points: 3 },
       ];
   };
   
   const performCalculations = (issues) => {
       // Aggregate data
       const totalPoints = issues.reduce((sum, issue) => sum + issue.points, 0);
       return { totalPoints };
   };
   

2. Update your manifest.yml: Register the new function in your manifest.yml:

   1
   2
   modules:
     function:
       - key: generate-report
         handler: generateReport.handler
         timeoutSeconds: 900
   

Step 3: Deploy Your Application

1. Deploy your Forge app:

   1
   2
   forge deploy
   

2. Install the app in your Jira instance:

   1
   2
   forge install
   

Step 4: Invoke the Long-Running Function

You can invoke the long-running function from your frontend or another backend service.

Conclusion

Long-running functions allow Forge developers to handle complex and time-consuming tasks efficiently. By following this tutorial, you have learned how to set up a realistic use case for generating reports from Jira data.