Forge Developer

Forge Developer

Last updatedMar 26, 2020

Rate this page:

Check whether Jira issues are assigned using a workflow validator

This tutorial describes how to create a Forge app that checks Jira issues are assigned when the issue transitions. You'll do this using a Jira workflow validator.

Jira board showing a notification message "The issue must have an assignee before transitioning."

If you prefer learning by looking at code, see the Open Pull Requests Validator example app for a more complex use of Jira workflow validators.

Before you begin

This tutorial assumes you're already familiar with developing on Forge. If this is your first time using Forge, see Getting started for step-by-step instructions on setting up Forge.

To complete this tutorial, you need the following:

  • The latest version of Forge CLI. To update your CLI version, run npm install -g @forge/cli@latest on the command line.
  • An Atlassian cloud site with Jira Software where you can install your app. You'll need to be an admin on the site to install the app.
  • A Jira Cloud classic project. You need to be an admin on the project to configure the workflow. We use a Jira Software Kanban project in this tutorial.

Create your app

The app contains the logic to check whether an issue is assigned to someone before they work on it.

  1. Navigate to the directory where you want to create the app.
  2. Create your app by running:
    1
    forge create
    1. Enter a name for the app. For example, issue-is-assigned-validator.
    2. Select the blank template from the list.
  3. Open the app directory to see the app files.

Add a workflow validator

The workflow validator runs when someone transitions an issue in Jira. Add a workflow validator by declaring jira:workflowValidator and function modules in the manifest. The jira:workflowValidator registers the details in Jira and the function contains the validation logic.

  1. In the app's top-level directory, open the manifest.yml file.
  2. Add a workflow validator entry under modules.

    1
    2
    3
    4
    5
    jira:workflowValidator:
      - key: issue-is-assigned-validator
        name: Issue is assigned validator
        description: Validates that the issue has an assignee before transitioning.
        function: validator

    The name and description display in Jira when choosing a validator to add to a workflow

  3. Connect the function module by updating the function module key to be: validator.

Your manifest.yml should look like the following, with your value for the app ID:

1
2
3
4
5
6
7
8
9
10
11
12
modules:
  jira:workflowValidator:
    - key: issue-is-assigned-validator
      name: Issue is assigned validator
      description: Validates that the issue has an assignee before transitioning.
      function: validator
  function:
    - key: validator
      handler: index.run
app:
  id: '<your-app-id>'
  name: issue-is-assigned-validator

Implement validation logic

Implement the run function to check that an issue is assigned before it transitions. The function returns true to allow the transition, or false to block the transition. When a transition is blocked, Jira displays the value of errorMessage.

  1. Open the src/index.js file and delete the contents.

  2. Create a run function to contain the issue validation logic by adding:

    1
    2
    3
    export const run = async ({ issue }) => {
       // Function code
    };
  3. Retrieve information about the issue from the Jira REST API, using the runtime API.
    1. In terminal, navigate to the app's top-level directory and install the runtime API package by running:
      1
      npm install @forge/api
    2. In index.js, import the runtime API at the top of the file by adding:
      1
      import api from "@forge/api";
    3. Call the Jira REST API in the run function to retrieve the issue details by adding:
      1
      2
      3
      const { key: issueKey } = issue;
      const response = await api.asApp().requestJira(`/rest/api/3/issue/${issueKey}`);
      const issueJson = await response.json();
  4. Return an object containing the validation result and an error message by adding:
    1
    2
    3
    4
    return {
     result: !!issueJson.fields.assignee,
     errorMessage: "The issue must have an assignee before transitioning."
    };
    The result is true if the issue has an assignee.

Your index.js file should look like the following:

1
2
3
4
5
6
7
8
9
10
11
12
import api from "@forge/api";

export const run = async ({ issue }) => {
  const { key: issueKey } = issue;
  const response = await api.asApp().requestJira(`/rest/api/3/issue/${issueKey}`);
  const issueJson = await response.json();
  
  return {
    result: !!issueJson.fields.assignee,
    errorMessage: "The issue must have an assignee before transitioning."
  };
};

Deploy and install your app

  1. Navigate to the app's top-level directory and deploy your app by running:

    1
    forge deploy
  2. Install your app by running:

    1
    forge install
    1. Select your Atlassian product using the arrow keys and press the enter key.

      Note: Running the forge install command only installs your app onto the selected product. To install onto multiple products, repeat these steps again, selecting another product each time.

    2. Enter the URL for your development site. For example, example.atlassian.net.

      View a list of your active sites at Atlassian administration.

Once the successful installation message appears, your app is installed and ready to use on the specified site. You can always delete your app from the site by running the forge uninstall command.

Add the app to your workflow

Start using the app by adding it as a validator in the workflow of a Jira Software classic project.

  1. Open Advanced workflow configuration and follow the instructions to add a validator. Select the validator that matches the name you defined in the manifest (1). The add validator to transition screen showing the Forge app is selected from a list
  2. Publish the workflow updates.

View your app

With your app installed and in your workflow, see it in action.

  1. Create an issue without an assignee in the project.
  2. Navigate to the board that displays the issue. If using a Scrum project, add the issue to the active sprint to make it visible on the board.
  3. Move the issue between columns.

You'll see the following error message display.

Jira board showing a notification message "The issue must have an assignee before transitioning."

Note, the location of the error depends on how you transition the issue. For example, when you transition the issue using the controls on the issue view, the error displays on the issue view.

Next steps

Check out an example app, continue to one of the other tutorials, or read through the reference pages to learn more.

  • See the Open Pull Requests Validator example app for a more complex use of Jira workflow validators. This app checks whether all pull requests are merged before an issue is resolved.
  • See the Automate Jira using triggers tutorial for information on using triggers to respond to user actions in Jira.
  • See the reference pages for more information on what you can do with Forge.

Rate this page: