Last updated Nov 9, 2023

Automation with Forge

Forge unlocks automation possibilities that go beyond automation within products, like Jira and Confluence. This includes the ability to implement complex logic and deeply integrate with external systems.

Note that the integration between Forge apps and product automation capabilities uses the generic Send web request component. There are no Forge-specific product automation components.

Usage

In general, we recommend using automation platform capabilities where available rather than building identical functionality in an app. There are also existing Marketplace apps that provide automation capabilities that could be considered before writing a bespoke app.

Conceptual overview

There are several ways in which Forge apps can automate tasks. An app can leverage automation features built into products, such as Jira, for example. Alternatively, an app can independently implement automation capabilities. These methodologies can work independently or in concert with each other, as shown below.

Patterns

There are four main patterns that define how automation can be built using Forge:

Implementing automation entirely with Forge
Extending automation with Forge
Triggering automation with Forge
Injecting custom logic in automation

Implementing automation entirely with Forge

Automation can be entirely implemented as a Forge app. In this pattern, the product automation capabilities are not used since Forge apps have the ability to subscribe to product events and can invoke product APIs.

Extending automation with Forge

In this pattern, automation may be implemented with product automation components that trigger a Forge app to complete the automation.

Triggering automation with Forge

A Forge app can respond to a Forge event, then perform some logic and conditionally invoke an automation to perform additional actions. There are a range of different kinds of Forge events, including product events similar to those available to product automations, as well as events that are triggered by non-product events.

Injecting custom logic in automation

In some cases, it may make sense to incorporate Forge capabilities within automation that starts and ends with product automation capabilities.

Example

The diagram below shows an example of a Forge app with automation capabilities that integrate with automations created with automation for Jira. There are three automations: add joke comment, add joke-added label, and add key labels.

The send web request automation component is configured to invoke the app’s web trigger, which handles the condition evaluated by the first part of the automation (the assignee of an issue is a specific user). The app then retrieves a joke from an external system, adds it as a comment to the issue, and invokes and add joke-added label automation by calling its incoming webhook component.

The add key labels automation is wholly implemented by the same Forge app. The app listens for comment added events. On receipt of an event, it checks the comment for certain keywords, and if detected, adds labels to the issue that relate to the keywords found.

Advanced considerations and tactics

Validating invocations from the send web request component: If your Forge app has a web trigger that will be invoked by the send web request automation component, the send web request automation component can be configured to send a custom header that acts as a secret shared between the automation component and the app. On receipt of the web trigger event, the app should check the header value. Use an environment variable in your app to store the secret. The following code will validate the header:

1
2
const headers = webtriggerPayload.headers;
const headerSecretObject = headers['shared-secret'];
const headerSecret = headerSecretObject ? headerSecretObject[0] : undefined;
const validated = headerSecret && headerSecret === process.env.SHARED_SECRET;

Constraining automations to specific contexts: It’s often the case that automation applies only to a specific context, such as a Jira project or Confluence space. Constraining Forge app automations to specific contexts can easily be achieved. When a Forge function is invoked outside of a user context, such as a product trigger, the function receives a payload or parameter that contains context information. See the product events documentation for more details.
Avoid circular loops: Be aware of the possibility of circular loops that result from multiple automations triggering from each other.
Permissions: For an app to invoke an incoming webhook automation component, the app will need to request a backend external fetch permission as follows:

1
2
permissions:
  external:
    fetch:
      backend:
        - 'https://automation.atlassian.com'

Process-intensive operations: If a Forge app needs to perform operations that will take significant computing power, time, or both, it may be necessary to implement in small processing chunks using the async events API. Doing this helps prevent the app from exceeding the Forge function invocation timeout.

Detailed information

Forge and product triggers

Product triggers

Forge app functions can register to receive trigger events for a range of different kinds of product events that are similar to the different kinds of triggers available within the built-in automation capabilities. When an app is invoked by a product trigger, information is passed to the app about the event causing the trigger, including contextual information, such as the project, issue, or page relating to the event.

More details:

Documentation: Product events
Tutorial: Automate with Jira triggers

Ad-hoc Forge triggers

Forge app functions can be triggered in an ad-hoc manner. This is useful where the triggering event occurs in an external system, and as explained above, having a product automation invoke a Forge function.

More details:

Documentation: Web trigger
Example app: Compass web trigger

Periodic Forge triggers

Forge app functions can be triggered in a periodic manner. This allows automations to execute on a scheduled basis.

More details:

Documentation: Scheduled trigger

Calling APIs from a Forge app

Calling product APIs

Forge apps can invoke Atlassian product APIs without the app developer needing to manage product credentials.

Import the Forge API package in your app, as follows:

1
2
import api, { route } from '@forge/api';

To check the status of a request, use status as shown below:

1
2
const result = await api
  .asApp()
  .[requestConfluence | requestJira](
    route`/rest/api/etc`
  );
const status = result.status;

More details:

Documentation: Product authentication

Calling external APIs

Forge apps can also make authenticated requests to external APIs using the fetch operation as follows:

1
2
import api from '@forge/api';

const response = await api.asUser()
  .withProvider('google', 'google-apis')
  .fetch('/userinfo/v2/me');

More details:

Documentation: External authentication
Example app: External authentication with Google Photos
Example app: External authentication with AWS Cognito

Invoking a product automation trigger

Invoking a product automation trigger involves a simple fetch request:

1
2
const payload = {
  ...
}
const options = {
  method: 'POST',
  headers: {
    'Accept': 'application/json',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(payload)
}
// Set this environment variable with forge variables set MY_WEBHOOK_URL https://automation.atlassian.com/[remainder of url of incoming webhook component]
const url = process.env.MYL_WEBHOOK_URL;
const response = await fetch(url, options);

More details:

Documentation: Forge basic fetch

Additional guides

The following resources provide additional guidance that will help you get started building Forge automation apps: