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.

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 - 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 Elements Connect generates the display template on the entire result set >> might lead to performance issues

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	$currentCustomfieldValue	Query & Template used	Notes
Basic - Generate list of options Executed to populate options a Elements Connect fields used in the basic search	(see below)		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:	(see below)		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	(see below)	equals to $userInput	Search	Jira Cache Jira caches results - Elements Connect is never called twice with the same user input during the same session ~ search The autocomplete on the ~ operator shall is not appropriate. However, it can't be deactivated for this operator solely.
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. `i.e.: "Elements Connect field" = "Hello world [10001]"` in this example, the field key used in search is `10001` . If the operand 2 does not contains square brackets [], Connect uses the entire value in the search. `i.e.: "Elements Connect field" = "10001"` in this example, the field key used in search is `10001` .
Execute JQL query (~ and !~ operators)	(see below)		Search	Elements Connect execute the search query generate display templates on the entire result set filter display templates generated during step 2, based on the operand 2 Apply a "contains" search (* is implicit)

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:

CODE

#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