See how to use the JQL syntax to search for Requirement Yogi links (Data Center only).
This page relates to Jira only. The Jira module is free, Data Center-supported, and its installation is described in Requirement Yogi for Jira configuration.
In Jira 11, the JQL search syntax is extended:
The requirementYogiLinks() and requirementYogiKeys() functions are removed in favor of this simpler method,
Requires Jira 11 and a custom field for your requirements (See Custom field),
Example | Intent |
|---|---|
"My Custom Field" = 'REQ-001' | The custom field contains REQ-001 |
"My Custom Field" = requirement('REQ-001') | Equivalent to the first syntax, but the function has more arguments |
… = requirement('REQ-001', 7) | The custom field contains a link to REQ-001 in baseline 7, |
… = requirement('SP', 'REQ-001', 7) | Requirement REQ-001, baseline 7, space SP |
… = requirement('SPACEKEY', 'REQ-001', 'CURRENT') | Requirement can only be in the current version. |
… = requirement('SPACEKEY', '*', '*') … = requirement('SPACEKEY', '*', 7) | Search for issues with links to requirements in a given space, or in a given baseline. Wildcards are accepted for the requirement key and the baseline, but not for the space key. When the baseline is specified, the space must be specified as well. |
"My Custom Field" ~ 'REQ*' | The custom field has links to requirements starting with REQ. The wildcard only works at the end, to search for a prefix. No other position works. |
… IN ('REQ-001', 'REQ-002') … IN(requirement('SPACEKEY', '*', 7)) | The custom field has links to either REQ-001 or REQ-002. The second syntax allows you to specify the space key and baseline. |
This new method for searching doesn’t have the limitations of the previous versions:
No limit on the number if matched issues,
No limit on the number if matched requirements,
No limit on the usage of != or NOT.
In 2.5, we've introduced the ability to search on the custom field directly:
Requires Jira 8.0+,
Create a custom field for requirements, in our example we will name the custom field: "RYLinks”
When you create the custom field, select the field type “RY Requirement Yogi links”, and that you have configured the relationship.
Edit the custom field and enable the "search template" on this field, named "Searcher for RY Links",
When you edit the search template, you will need to perform a re-index action so the search syntax can work properly. A popup will usually appear but you can go into System Administration → Advanced → Index, and make sure to tick “Full re-index"
You can now use the search syntax below.
Example | Intent |
|---|---|
RYLinks in requirementYogiKeys('REQ-001') | All custom fields which contain the requirement REQ-001. |
RYLinks in requirementYogiKeys('REQ-%') | All custom fields which contain one of the REQ-... requirements. |
RYLinks in requirementYogiKeys('REQ-001', 3) | Requirement REQ-001, in baseline 3 |
RYLinks in requirementYogiKeys('REQ-001', "CURRENT") | Requirement REQ-001, in current version. |
RYLinks in ('REQ-001', 'REQ-002') | A list of requirements (no baseline possible) |
It is not possible to specify the space key or the Confluence instance,
It doesn't work for Jira 7.13.
In 2.2.5, we've introduced a JQL Function named requirementYogiLinks to search for issues that are linked to RY requirements.
Usage: issue in requirementYogiLinks('applink_id', 'relationship', 'space_key', 'key#baseline_number')
Examples :
Example | Intent |
|---|---|
issue in requirementYogiLinks('REQ-001') | Issues linked to requirement REQ-001 |
issue in requirementYogiLinks('REQ-001#3') | Issues linked to requirement REQ-001 in baseline 3 |
issue in requirementYogiLinks('PROD', 'REQ-001') | Issues linked to requirement REQ-001 and spaceKey PROD |
issue in requirementYogiLinks('abcd-fff1-acef-4343', 'resolves', '*', '*') | Issues linked to requirements from applink 'abcd-...' with relationship "resolves" |
issue in requirementYogiLinks('abcd-fff1-acef-4343', '*', '*', '*') | Issues linked to requirements from applink 'abcd-...' |
issue in requirementYogiLinks('resolves', '*', 'REQ-001#1') | Issues linked to requirement REQ-001 and baseline 1 with the relationship resolves |
Any argument can be replaced with '*' if it's not relevant.
The NOT keyword doesn't work well yet.
When deploying to customers, we've noticed many of them use JQL to detect issues which don't have requirements yet. This is not a use case we've thought of, and it may perform badly. Watch https://requirementyogi.atlassian.net/browse/RY-488 to keep updated.