Linked Issues Validator

Created by David Fischer (Appfire)
Last updated: Jun 16, 2022 by Richard Stone[Appfire]

Are you using JMWE for Jira Server and Data Center and want to learn how to use this validator? Head to our documentation here.

  • This validator does not work with remote links (links to Jira issues residing on another Jira instance/server).

  • Beware of the default "relates to" link type, which can cause confusion. The problem stems from the fact that "relates to" is both the inward direction and the outward direction of the "Relates" link type. We recommend that you rename one of the directions to "is related to" to avoid confusion. This can be done on the Issue Linking Jira admin page.

  • Jira portfolio links are not supported in Jira expressions and hence not available in the validator.

To add 'Linked Issues Validator' to a transition:

  1. Click Edit for the workflow that has the transition you wish to configure the validator on.

  2. In the Workflow Designer, select the transition.

  3. Click Validators in the properties panel.

  4. Click Add validator.

  5. Select Linked Issues Validator from the list of validators.

  6. Click Add to navigate to the Linked Issues Validator screen where you can configure the validator as needed. See configuration details here.

  7. Click Add to add the validator on the transition.

On the Service Management portal view of a request, the customer will not see the Error message when the validator fails. This is due to a known limitation (JSDCLOUD-5853) with Atlassian.

When you add this validator to a transition and trigger the transition, the add-on checks the specified condition on linked issues (existing and ones added during the transition) that are of the specified issue link type and issue type; all the other linked issues will be considered as satisfying the condition and hence pass the validation. You can further customize the validation using the details mentioned in the next section.

Configuration details

Configure the following:

  • What to validate: Select one of the following validations to be run on the linked issues to allow or stop the transition from proceeding further:

    • Require the creation of issue links on the transition screen: At least one issue link must be added on the transition screen, and that link must be of the specified Issue Link Type and respect the constraints in the What to enforce on linked issues section.

    • Validate issue links added on the transition screen, if any: If issue links are added on the transition screen, validate that they are of the specified Issue Link Type and must respect the constraints in the What to enforce on linked issues section.

    • Require certain linked issues (default option): The transition cannot proceed if linked issues respect the specified Issue Link Type and must respect the constraints in the What to enforce on linked issues section. These issue links can either already exist or be added on the transition screen.

    • Check linked issues: If the specified linked issue(s) exist, the transition cannot proceed unless these linked issues respect the specified Issue Link Type and must respect the constraints in the What to enforce on linked issues section. These issue links can either already exist or be added on the transition screen.

    • Forbid certain linked issues: If any linked issue with the defined Issue Link Type and the constraints mentioned in the What to enforce on linked issues section exists, the transition cannot proceed. These issue links can either already exist or be added on the transition screen.

  • Issue Link Type (mandatory): Select the issue link type that links the current issue to the linked issues to check the specified condition against. Leave "Any (default option)" for no restrictions.

  • What to enforce on linked issues:

    • Issue Type (mandatory): Select the issue type of the linked issues to check the specified condition against. Leave "Any (default option)" for no restrictions.

    • Additional condition: Select one of the following:

      • None: Select this option for no additional condition.

      • At least one linked issue must satisfy the condition below: Select this option for at least one linked issue to satisfy the condition specified in Jira expression. 

      • Every linked issue must satisfy the condition below: Select this option for every linked issue to satisfy the condition specified in Jira expression.
        Jira expression: Enter a Jira expression to be checked on all linked issues. If the Jira expression evaluates to true for all linked issues, only then the workflow condition will pass. If it evaluates to false for at least one linked issue the workflow condition will fail. See How to insert information using Jira expressions for information on writing a Jira expression.

Avoid errors in Jira expressions

When a Jira expression throws an error, Jira considers the result as false, and hence the workflow validator fails (for all linked issues irrespective of the option selected under "Additional condition"). The best way to avoid errors in your Jira expressions is to test your Jira expressions against an issue using the "Jira expression tester" before saving the validator. Here are typical problems you need to look out for:

  • null values: if your Jira expression accesses properties of an object that is null, then your Jira expression and thereby your workflow validator fails with an error. For example, to check that the issue's parent is a Story if you provide the Jira expression:

    1 issue.parent.issuetype.name == "Story"

    when tested against an issue without a parent, the Jira expression will return an error "Type null does not have any properties". To handle this you should include an expression to test that the issue has a parent.

    1 !! issue.parent && issue.parent.issuetype.name == "Story"

  • Error message (mandatory): Customize the error message that needs to be displayed if the validator fails.

  • Validator scope: Control when to run the validator using this option. Check this option if you want the validation to be performed only in certain cases, such as if the issue is of a specific issue type or only if the issue is unassigned, or more generally satisfies an arbitrary Jira expression mentioned in Jira expression displayed when this option is selected.

Use case

A typical use of this workflow validator is to validate during the transition that the current issue has linked issues or during the transition, specific linked issues are added to the transition screen.

Consider a use case where you want to validate on the Start Progress transition that the current issue has at least one subtask in the In Progress status. To configure this:

  1. Add the “Linked Issues validator” to the “Start Progress” transition.

  2. Select “Required certain linked issues” under “Mode”.

  3. Select “Issue Link Type” as “is Parent of”.

  4. Select “At least one linked issue must satisfy the condition below” under “Additional Condition”.

  5. Input the following code under “Jira Expression”:

    1 linkedIssue.status.name == "In Progress"

  6. Input the Error message: “No subtask in In Progress status”.

  7. Save the validator.

  8. Publish the workflow.