Learning Goal: How to build dependent (or nested) search fields in a Jira work item using “External Data for Jira."
Learning Level: Advanced
Use Case: We have a huge customer list (“Tutorial Customer List”). We want to look up a specific customer and select one of their existing orders.
Before we begin, please make sure you meet the following basic requirements:
-
A Company Managed Space
-
Existing and activated Custom Search Fields
Configuring the Parent Search Field
Before we can set up a dependent search, we need to have an initial search field that our second search will be dependent on. So our first step is to create and set up the parent search.
We do this by creating a default search field with our “Tutorial Customer List” as data source.
We now need to add a JSONPath to filter the raw results. In our case, we want the JSONPath to refer to the company, as the company name is supposed to be the initial search outcome we later want to refer to.
Explanation In Detail:
$.results[*].company: Our JSON list is named "results"—so we add that to our Select List Repository field like this. To parse all results from the list, we need to add an asterix in square brackets. The next step is to add the JSON path that refers to the company. See JSONPath Basics for more syntax guidance.
$.id: JSONPath to our id, which will be the unique identifier.
$.name: As our first search result is supposed to be the company name of our customer, we’ll put the JSONPath to the company’s name here. Same for the value field, in which the search result will be displayed later on.
Now we just have to select the Target Jira Field, which we have created beforehand, before we save and exit the parent search setup.
Configuring the Child Search Field
Now we need to create a search field that is dependent on the search results of our parent search. Compare the available options in Comparison between various Search Fields.
Since in our use case we want to search for the products of a previously selected company, we need to add a Context Filter to our search, using the same Data Source as before.
Adding a Context Filter
We start with the name of the repository $.results and then add the company name, @.company.name==''). The dedicated Context Filter guide covers the available filter inputs and syntax.
For a better understanding of how this expression works, we could temporarily add a single company name here. Like, for example: $.results[?(@.company.name=='Sporer Inc')]. See Expression Builder for help constructing expressions.
This would render the raw results of all data objects of the company “Sporer Inc."
Yet of course, we don’t just want to look up products from a single defined company but want to have a dynamic dependency on the respective results of our parent search.
In this case we need to add the path to the associated work item field, which is “customfield 10077." For available work item variables, see Use Jira Work Item Values Variables.
Thus, the correct expression for a dynamic context filter will be
$.results[?(@.company.name=='{$.issue.fields.customfield_10077}')]
For more examples of building expressions with values, operators, and JSONPath queries, see Expression Basics.
Now we need to select the list repository for our child search. For more detail on repository paths in the Fetch search mode, see Search Field - Fetch.
Explanation in Detail:
$.[*] to choose all items from the filtered results. This is a common JSONPath pattern for selecting every item in a list.
$.id: the JSONPath to our ID, which will again be the unique identifier.
$.name: the JSONPath to the company’s product. We add “name” as Search Field path, as we want to look up the name of the products (this doesn’t refer to the company’s name but to the name of the product). Same for the Value Field, in which the search result will be displayed later on. See Template Syntax for related display formatting.
The results should now be rendered correctly.
Adding additional values and styling to the search output
Let's assume that we want to have not only the product names as a result, but also their EAN numbers. In this case, we have to add that path too.
Explanation in Detail:
If we add another value, in this case the EAN number, to the Value Field, we need to put the individual JSONPaths in curly brackets in the Value Field as well as in the (optional) Value Label field like this. For more examples, see Template Syntax.
{$.name} - {$.ean13}
We can also add styling elements to label the additional values.
For example:
{$.name} - EAN-13: {$.ean13} will later be rendered as “Product Name - EAN-13: XXXXXXXXXXXXX”.
{$.name} - [EAN-13: {$.ean13}] will be rendered as “Product Name - [EAN-13: XXXXXXXXXXXXX”]
If we want to add an optional Search Template, we need to use mustache syntax, which means we don’t need the §. as a prefix but have to add another curly bracket layer to the expression. We can also use styling here. So in our case, the expression could look like this:
{{ name }} - [EAN-13: {{ ean13 }}] which would render as “Product Name - [EAN-13: XXXXXXXXXXXXX]”.
(Of course, you can add whatever values you want here; maybe you want to get the color or the price instead of EAN)
This is how your results should now look in the Jira Work Item:
