This guide provides detailed instructions on how to effectively use JQL queries to apply filters using Multi-Level Cascading Select.
In Cloud instances, Multi-Level Cascading Select is optimized for JQL filtering. We strongly suggest searching for issues using advanced JQL search instead of basic search.
How to refer to MLCS fields in a JQL query
There are two ways to refer to MLCS fields in a JQL query:
By field name:
Use the name of the of a MLCS field to refer to that specific custom field. For this search, a JSON-like value is required.
To assist you in writing the JSON-like value, enter the name of the MLCS field along with a valid operator to retrieve all unique selection sets from your issues for that specific field.
By issue property:
issue.property[“com.sourcesense.mlcs”].lv(n) and it’s alias, mlcs_lv(n). They both work similarly. The latter is an alias that we created to make it easier to write the property. Change the (n) with the lv number to match the level of the option you are looking for.
lv is zero-based, meaning that the first level (root) is referred to as lv0.
In the following section, we will see how we can exploit the MLCS integration in JQL queries to search for issues, even without admin privileges (therefore with no access to the MLCS field configuration).
Find options level by MLCS field name
If we do not have admin access to the custom field page and we do not know the configuration tree, we can use the suggestions from the autocomplete mask activated by typing the operator after the name of the field. This will retrieve all the occurrences of that field and the relative selections.
Once the suggestion is chosen, a JSON-like value populates the JQL query, indicating the filter applied. Now, we have access to the option names (label) and the relative IDs (value).
Search for issues where the option appears in any MLCS field.
You can specify the name (label) of an option and the level where it’s supposed to be, to filter issues on any MLCS field that contains that selection. This is the syntax: mlcs_lv(n) = <option label>.
Use case scenario
The goal is to select the issues that contain the option “1.1”. Multiple MLCS custom fields share this same option, and we need to retrieve all of them.
In this use case, we do not specify the custom field ID, so the syntax will be: mlcs_lv1 = 1.1.
Issues with different MLCS custom fields appear in the results, all with the same option selected (1.1). Note that even if lower levels of options are selected, as long as the 1.1 option is present, the issue is shown (1, 1.1, 1.1.1).
Search for issues where the option appears in a specific MLCS field.
If you are looking for a selection in a particular field, you can narrow your search by adding the field ID:
mlcs_lv(n) = <cf ID>:<option label> .
Use case scenario
Let’s exploit our sample configuration again:
The goal is to find issues where option 1.1 is selected, but this time, we need to retrieve only those where the option appears specifically in the AAA MLCS 1 field. We know the custom field ID (conveniently shown in the custom field Administration section) . In this use case, the syntax will be: mlcs_lv1 = 10063:1.1 .
Issues with the field AAA MLCS 1 are displayed in the results, all with the same option selected (1.1).
Limitations
lowest level searchable
The lowest searchable level is level 5. Since lv is zero-based, searches can range between mlcs_lv0 and mlcs_lv4.