Search view configuration
Search view
Available for LIVE FIELDS
By default, Elements Connect uses the Edit view configuration when using an Elements Connect field in a JQL search.
While it works fine in most cases, you might have to set a custom Search configuration.
![](../__attachments/10980524444/Search%20view.png?inst-v=9fdb14ed-4bc9-4150-9682-af9fdd6c0846)
It's recommended to set a custom search query if:
- there is a dependency to $issue in the edit query
- the edit query does not return a full list of options
It is recommended to set a custom search template if
- HTML is used in the display editor template
Operators
Terminology
<operand 1> <operator> <operand 2>
- operand 1 - the Elements Connect field
- operator - one of:
- =
- !=
- in
- not in
- is not empty
- is empty
- ~
- !~
- operand 2 - a Elements Connect field value (or a list of Elements Connect field values)
Operator | Operand 2 | Matches issues ... |
---|---|---|
= | A valid Elements Connect field value | ...where the field is set to operand 2 |
!= | A valid Elements Connect field value | ...where the field is not empty and set to a value different than operand 2 |
in | A list of valid Elements Connect field values | ...where the field is set to a value listed in operand 2 |
not in | A list of valid Elements Connect field values | ...where the field is not empty and not set to a value listed in operand 2 |
is empty | X | ...where the field has been set but is currently empty Does not return issues where the field has never been set. |
is not empty | X | ...where the field is not empty |
~ | A string value (free text) | ...where the display template generated by the Search query contains the value of the operand 2 |
Search contexts
Contexts
Search can divided in three parts.
Basic search
Simple UX where users can build JQL queries using simple criterion.
Advanced search
More powerful than the basic search, experienced users can build their own JQL query using advanced operators.
Search execution
The execution of the JQL query.
The execution works the same wether the query has been built from the Basic or Advanced search view.
Variables available / context
Depending on the context, some variables might not be available - everything is summarized in the table below.
$issue | $userInput | $currentCustomfieldValue | Query & Template used | Notes | |
---|---|---|---|---|---|
Basic - Generate list of options Executed to populate options a Elements Connect fields used in the basic search | Search | ||||
Basic - Convert selected values to JQL The basic query builder generates JQL queries. The conversion of the values selected by users to a JQL query is under the responsibility of the app that provide the field. This query is used to convert this: into this: | Search | ||||
Basic - Generate Issue navigator summary Used to generate the values displayed in the box from the values selected in the field editor | Issue navigator summary | ||||
Advanced - Generate list of options Used to generate the field options list in advanced mode | Search | Jira Cache
~ search The autocomplete on the ~ operator shall is not appropriate. | |||
Execute JQL query (all operators except ~ and !~) | The Elements Connect query is not executed when the JQL query is executed. How it works? Elements Connect get the field keys from the query - the value between the [] at the end of the query - and pass to Jira where it is used in the Lucene query.
in this example, the field key used in search is If the operand 2 does not contains square brackets [], Connect uses the entire value in the search.
in this example, the field key used in search is | ||||
Execute JQL query | Search |
|
How can we handle the different contexts in the search query?
We can get the current context from a velocity variable (i.e.: $context) and explain in the documentation which variable is available for each context. Example:
#if($context.name == $context.SEARCH_BASIC_GENERATE_OPTIONS)
## Available variables:
## - $issue
## - $userInput
## - $currentCustomfieldValue
#elseif($context.name == $context.SEARCH_BASIC_GENERATE_JQL_QUERY)
## Available variables:
## - $issue
## - $currentCustomfieldValue
#elseif($context.name == $context.SEARCH_ADVANCED_GENERATE_OPTIONS)
## Available variables:
## - $issue
## - $userInput
#elseif($context.name == $context.SEARCH_ADVANCED_TILDE_SEARCH)
## Available variables:
## - $issue
#end
Dependencies on $issue limitations
Only attributes set in the search bar are available
Attributes not set are evaluated to an empty string.
Examples:
JQL query | $issue.project value |
---|---|
Elements Connect-field = | empty |
project = ABC and Elements Connect-field= | ABC |
project = ABC OR project = BCD and Elements Connect-field= | ABC, BCD |
project in (ABC, BCD) and Elements Connect-field= | ABC, BCD |