Rate this page:
The jira:workflowValidator
module creates a workflow validator that can be configured on workflow
transitions in company-managed projects.
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{ "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 2jira: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 2export const validate = (args) => { const issueKey = args.issue.key; return { result: issueKey.startsWith('PRO'), errorMessage: 'Only PRO project can use this flow' }; }
In a jira:workflowValidator
module, calls to an Atlassian API must be done as the app developer by using api.asApp().
Making requests on behalf of a user with api.asUser()
won’t work, because there's no interaction between the app and the user during the workflow transition, so there is no way to display a consent screen to the user.
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 2jira: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.
Property | Type | Required | Description |
---|---|---|---|
key |
| Yes |
A key for the module, which other modules can refer to. Must be unique within the manifest. Regex: |
name | string | Yes | The name of the validator displayed in the workflow configuration. |
description | string | Yes | The description of the validator, shown when adding the validator to a transition. |
function | string | The validator requires either the function or the expression in your Forge app. Only one of the two properties must be present in your Forge app. | A reference to the function module that evaluates the validator. |
expression | string | The expression used to validate whether or not the transition should be allowed.
The expression can return either a boolean value or a string. Returning a string overrides the error message defined in the manifest – the returned string is shown to the user as the error message instead. The expression is evaluated with the following context variables: | |
errorMessage | string | The error message to show when the validation fails. If `errorMessage` is not provided, the default error message will be displayed. |
Rate this page: