Jira workflow validator (beta)

The jira:workflowValidator module creates a workflow validator that can be configured on workflow transitions in company-managed projects.

Validating with lambda functions

The function configured for the validator is invoked on every transition that the validator has been added to. When the function is invoked, it is passed an argument that contains information about the transition, that is:

1
2
3
4
5
6
7
8
9
10
11
12
13

{
  "issue": {
    "key": "issue key"
  },
  "transition": {
    "from": {
      "id": "status id"
    },
    "to": {
      "id": "status id"
    }
  }
}

The function returns an object containing two properties:

• result - a boolean value indicating whether the transition is allowed.
• errorMessage - the error message to show if the result is false. Otherwise, this property is ignored and doesn't have to be included.

For example, to create a validator that allows transitions only for issues in the project with key PRO, declare it like this in the manifest:

1
2
3
4
5
6
7
8

jira:workflowValidator:
  - key: my-forge-workflow-validator
    name: Project is PRO validator
    description: This validator will allow the transition only if the project is PRO.
    function: validate
function:
  - key: validate
    handler: status.validate

To implement the actual logic in the src/status.js file:

1
2
3
4
5
6
7
8

export const validate = (args) => {
  const issueKey = args.issue.key;

  return {
    result: issueKey.startsWith('PRO'),
    errorMessage: 'Only PRO project can use this flow'
  };
}

Validating with Jira expressions

It’s possible to provide a Jira expression instead of a function if you’re only checking the state of the current issue.

For example, a validator that checks if the issue is assigned would look like this:

1
2
3
4
5
6

jira:workflowValidator:
  - key: my-forge-workflow-validator
    name: Issue is assigned validator
    description: This validator allows the transition where the issue has an assignee.
    expression: issue.assignee != null
    errorMessage: "The transition failed because no one is assigned to the task. Assign the task to a user and try again."

The issue validated by the expression includes changes made on the transition screen, which makes this way of defining validators particularly suitable for cases where the state to validate can be modified during the transition.

Properties