Forge-ing Simple Solutions: Combining Automation for Jira with Forge

[#1]

When talking about automation and Jira cloud, the first thing that comes to mind is Automation for Jira (A4J), and rightfully so; it can solve quite a number of use cases. Automating your repetitive tasks using a no-code rule builder, that's the dream. However, there are instances wherein a built-in action is not available and a custom app would best fit e.g., creating a new board, or creating a new sprint – this is where Forge comes in as you can perform these actions by using REST APIs invoked from a Forge app.

But wait, why not use Forge all the way? Yes, for most issue-triggered use cases, there are Forge Jira events that you can use to trigger an action but currently, Sprint-related triggers aren’t one of them.

That said, we can integrate A4J and Forge to unlock new automation use cases.

What we’ll build today

In this article, I’ll demonstrate how to set up a trigger listening for a Jira Sofware event (e.g., Sprint completed) in A4J and call a Forge app via a web trigger URL.

We’ll use the following to make this happen:

• Automation for Jira

• Web trigger module to expose a URL that the automation can call

• Jira Software REST APIs to make the desired changes

At the end of this article, you’ll be able to trigger your Forge app from an event received by A4J.

How we can build it

Step 1: Create a Forge app using the webtrigger template

1. Open your CLI and call forge create

2. Name your app e.g., forge-web-trigger-example

3. Select the category Triggers and Validators

4. Select webtrigger as the template

Step 2: Deploy and install your app in your instance

In your CLI, go to your project directory and call forge deploy, followed by forge install and choosing the Jira cloud instance that you want the automation to run on.

Step 3: Get the web trigger URL

The web trigger URL will be used as a parameter for your A4J action. To secure this, instructions can be found in this link.

1. Get the app’s installation ID by calling forge install list in your project directory

2. Call forge webtrigger <installationId> then select the web trigger you want to build the URL for; this should only be one if there were no modifications to the code

3. Copy the generated web trigger URL

By default, the URLs provided by forge webtrigger have no built-in authentication. As such, anyone can use the URL (and, by extension, invoke its related function) without providing an authentication token. You should keep these URLs secure.

Alternatively, you can also implement authentication inside the trigger itself. For example, you can add a check for an Authorization header in the request and validate any provided token.

-- Forge Webtrigger docs

Step 4: Create the A4J automation rule

1. Create a trigger e.g., Sprint completed

2. Add the action to Send web request

3. In the Web request URL, key in the web trigger URL that you got for your Forge app

4. You can send additional information that you would need in your Forge app to make a REST API call. In this screenshot, I am passing sprintId, and sprintName while using the sprint smart values

5. Optional but recommended Add the Authorization header that contains a unique token (feel free to generate one) that you will later validate within your Forge app - this will make your security team happy 🙂

6. Publish the rule

 

After this step, you can already trigger your Forge app once you close a sprint. Not so hard, is it? 🙂

Step 5: Update your Forge app to call a REST API

You can perform any action once the Forge app is triggered, but in this article, let’s do a quick Jira Software REST API call as an example.

Install the API package

1. In your CLI, go to your project directory

2. Install the API package by running npm install @Forge/api 

Modify index.jsx

1. Add the necessary import statement to call a REST API (see code below)

2. Refactor buildOutput() to remove unnecessary items in it i.e., X-Request-Id, and change the statusCode and statusText to 204 and No Content, respectively

3. Make the run() function async since we are to call the async requestJira function in it

4. Inside run(), call the REST API

For simplicity and illustration purposes, I only used the Get sprint API. However, you can call any supported Jira, JSM, and JSW REST API depending on your use case e.g., if you prefer to automatically create a new sprint, and set a sprint property every time a sprint is closed, then that is also possible.

Once done, index.jsx should look something like this:

// Necessary import for calling Jira REST APIs
import api, { route } from "@forge/api";

const buildOutput = () => ({
  headers: {
    'Content-Type': ['application/json']
  },
  statusCode: 204,
  statusText: 'No Content'
});

export const run = async (req) => {
  // This is the request from A4J
  console.log(req);
  
  // Parses the request body from A4J as it is a string when we got it
  const parsedBody = JSON.parse(req.body);
  
  // Gets the Authorization header
  // Yes, the header keys are received in lower case
  const authToken = req.headers['authorization'];

  // If you decided to add Authorization header in the A4J request
  // This is a basic handling of that token
  if(authToken != 'Bearer mySecureToken' ) {
    console.log('Invalid token');
    return {
      statusCode: 401,
      statusText: 'Unauthorized'
    };
  }

  // console.log('Correct token');
  
  // Calling the GET sprint API passing a parameter from the A4J action 
  // You can change the API depending on your use case
  const response = await api.asApp()
                    .requestJira(route`/rest/agile/1.0/sprint/${parsedBody.sprintId}`);
  const data = await response.json();

  // console.log(data);  

  const result = buildOutput();
  return result;
};

Before calling forge deploy, make sure to add the necessary permissions in the manifest.yml file depending on the REST API resource you are calling, and in this case, this is the permission added.

permissions:
  scopes:
    - read:sprint:jira-software

Since the manifest file has been modified be sure to call forge install --upgrade after a successful deployment.

That’s a wrap!

In these few steps, we can further expand the use cases that Jira Cloud family (including JSM and JSW) can support making our everyday lives run smoother with the help of automation.

Let us know in the comments below if you have any Automation use cases you want to share.

[Aaron Geister]

This is amazing information thanks for sharing.