Automate workflows with Forge
10 min
By the end of this lesson, you’ll be able to:
- Trigger actions based on product events.
- Use Forge to build automation rules.
Why automate with Forge?
Automation is a powerful way to eliminate repetitive tasks and streamline your team's work across Jira, Confluence, and other Atlassian tools.
Built-in automation rules in Jira and Confluence offer many possibilities, but they have limits when it comes to customized workflows or integrations with external systems. That’s where Forge comes in.
Using Forge, you can:
- Create custom triggers for product events.
- Write your own logic to define what happens when those events occur.
- Extend automation beyond what’s available in built-in rules.
Trigger actions from product events
In Forge, triggers let you listen for specific events in an Atlassian product. These could be events like:
- A work item created in Jira
- A comment added to a Confluence page
- A field updated
- A user added to a project
Triggers are declared in the app’s manifest.yml file and linked to a function that will run when the event happens.
👉 For example: Automatically label new Jira work items with a “Priority” label if it’s missing.
How it works
👇Click the icons below to view each step of the automation process.
Let’s look closer at this example to label new Jira work items as “Priority.”
When building automation with Forge:
Define which event your app should respond to. You define this in the manifest.yml file using a trigger module.
Here’s how you define that in the manifest:
Here’s how you define that in the manifest:
1modules:2 trigger:3 - key: auto-priority-label4 function: assignLabel5 events:6 - avi:jira:created:issueThe trigger listens for the avi:jira:created:issue event and runs the assignLabel function when a new work item is created.
Each trigger is then connected to a Forge function that contains the logic you want to run when the event occurs. You define the behavior of your automation inside a function file, typically found in the index.js.
This function receives event data and can use Forge APIs to perform actions, like updating the work item.
1import api, { route } from '@forge/api'2export async function run(event) {3 const issueKey = event.issue.key;4 const labels = event.issue.fields.labels || [];5 if (!labels.includes("Priority")) {6 await api.asApp().requestJira(route`/rest/api/3/issue/${issueKey}`, {7 method: 'PUT',8 headers: {9 'Accept': 'application/json',10 'Content-Type': 'application/json',11 },12 body: JSON.stringify({13 fields: {14 labels: [...labels, "Priority"]15 }16 })17 });18 }19}This code is inserted into your function file. The function name (run in this case) matches what you’ve linked in the manifest. This function checks whether the new work item has a "Priority" label, and adds one if it doesn’t.
Build more complex custom automation rules
Triggers are just the start of your automations. You can build full automation rules using Forge by writing your own logic in the app’s functions. You can make decisions, call APIs, or integrate with third-party services like Slack.
👉 For example: Notify a Slack channel when a support work item is created.
You can build this by combining a trigger with an external API call (in this case, Slack):
- Listen for the avi:jira:created:issue event.
- Check if the work item type is “Support.”
- Send a message to a Slack webhook.
Let’s look at what this looks like in the manifest file:
1external:2 fetch:3 backend:4 - hooks.slack.comAnd the function logic:
1import { fetch } from '@forge/api'2export async function run(event) {3 const issue = event.issue;4 const type = issue.fields.issuetype?.name;5 if (type === "Support") {6 await fetch("https://hooks.slack.com/services/your-webhook-url", {7 method: 'POST',8 body: JSON.stringify({9 text: `Support issue created: ${issue.key} - ${issue.fields.summary}`10 }),11 headers: { 'Content-Type': 'application/json' }12 });13 }14}